Part 2 of 6 Working through your agent
Decisions, findings and dead ends
By the end of this chapter the reason one approach was dropped is written where whoever picks the work up will read it first, a thing that was tried and failed is recorded so that nobody spends the same two days finding out again, and a decision taken once reaches every task underneath it without anybody remembering to link it.
A task says what to do. It has nowhere to put why, and why is the thing that gets lost first and costs the most when it goes.
You are still not typing commands. You are saying what you concluded, and your agent is writing it down somewhere it will be met rather than searched for.
The work so far
The website rebuild as Filing work, and what can be started left it: five tasks, one of them finished, and the agent's own account.
uv tool install subroutine
subroutine init
subroutine project create web "Website rebuild"
subroutine agent create claude --profile worker --project web --store
subroutine add "Write the copy for the home page +web"
subroutine add "Choose a typeface for the headings by Tuesday +web"
subroutine add "Agree the new navigation +web"
subroutine add "Build the new navigation +web ~1d"
subroutine add 'Audit the third-party scripts +web !3/2'
subroutine link 3 blocks 4
subroutine done 3
{
"mcpServers": {
"subroutine": {
"command": "subroutine",
"args": ["mcp"]
}
}
}What happened, and what you concluded
Two things, and keeping them apart is most of this chapter.
A comment is what happened. It is dated, it is attached to one item, and nobody revises it. Your agent writes one as it goes:
subroutine_comment(ref=4, body="Tried a mega-menu and it was unreadable on a phone.")
A document is what somebody concluded. It outlives the task that produced it, it can be revised, and it gets a number of its own:
subroutine_document(title="Navigation stays one level deep", type="decision", project="web", body="A mega-menu tested badly on a phone, and the second level was only ever four links. One level, and the four go in the footer.")
The title carries the conclusion, not the topic. Navigation stays one level deep tells somebody the answer from a list. Navigation options makes them open it to find out, and most of them will not. That is the whole difference between a document somebody reads and a document somebody means to read.
type says what kind of thing it is, and it is not decoration: it is how somebody scanning a list knows which ones bind them. A decision settles something. A finding records what you learned. A design describes how something works. A dead end says what not to try.
Putting it where the work is
A document filed in a project is findable. A document joined to the task it governs is unavoidable, which is the one you want:
subroutine_link(ref=6, type="documents", other=4)
subroutine_show(ref=4)
Read first is the point of the whole chapter. Whoever opens that task in six weeks meets the decision above the work, not in a wiki page they would have to know existed. One call put it there.
Underneath it are the two halves kept apart. Documented by says the document and the task are joined. The dated line at the bottom is the record of the afternoon that produced it. The comment says a mega-menu was tried; the decision says what was concluded from trying it. Neither can do the other's job, and a chapter's worth of arguing about which to write is usually a sign that both belong.
The name on that line is the agent's, not yours. @claude wrote it, because the agent has an account of its own from the first chapter. Had it been holding your credential, the record would say you sat down and tried a mega-menu.
A dead end is worth as much as a decision
subroutine_document(title="Do not generate the navigation from the sitemap", type="dead_end", project="web", body="It goes stale the moment a page moves, and the build cannot tell. Tried in the prototype, and it cost two days.")
Nobody writes these down, and they are the ones that cost twice. A good idea that does not work looks exactly like a good idea, so the next person to arrive has it too, and spends the same two days finding out. Recording it costs one call on the day you already know.
Give it the same treatment as the decision: file it in the project, and join it to the task where somebody would have the idea again.
subroutine_link(ref=7, type="documents", other=4)
A finding outlives the session that made it
A decision settles what to do. A finding records what is true, which is the thing an agent will otherwise establish again from scratch every time its context ends:
subroutine_document(title="The analytics tag loads the consent banner a second time", type="finding", project="web", body="Both are injected by the tag manager, and the banner has no guard against being mounted twice.")
subroutine_link(ref=8, type="documents", other=5)
That took an afternoon of reading somebody else's JavaScript. It is now a sentence that survives the session, and the next agent asked to look at the script audit is handed it before it opens anything.
A decision that reaches everything beneath it
Building the navigation has turned out to be a piece of work rather than a task, so your agent files what it is made of underneath it:
subroutine_add(text="Write the dropdown markup +web", parent=4)
subroutine_add(text="Check the navigation on a phone +web", parent=4)
Nobody joined those new tasks to anything, and nobody went back to the decision. Open one of them anyway:
subroutine_show(ref=9)
Both came down from the parent, and each says where it came from. That is what makes it usable rather than spooky: an agent handed a rule with nowhere to check it can only comply, and from #4 is the item it goes and reads when the rule seems wrong.
This is the half that is easy to underrate. Joining a document to one task is filing. Joining it to the work it governs means every task filed underneath that work afterwards, by anybody, months later, arrives carrying it.
A decision closer to the work sits above one further away:
subroutine_document(title="The dropdown opens on click, not on hover", type="decision", project="web", body="Hover has no equivalent on a touchscreen, and the phone is where this was already going wrong.")
subroutine_link(ref=11, type="documents", other=9)
subroutine_show(ref=9)
Nearest first, and the one written on the task itself carries no from at all, because it did not come from anywhere else. A general rule about the navigation and a specific rule about this dropdown are both in force, and they are in the order somebody would want to read them.
So the reasoning now sits beside the work rather than in somebody's head: what happened, what was concluded, what not to try, what turned out to be true, and a heading that puts the binding ones in front of whoever picks the task up. All of it is still your agent writing down what you settled between you.
The next chapter is the case where you have not settled it, and the agent knows it cannot.