07 — Working with specs and an agent
What you will have at the end: one idea taken from a sentence to an agreed decision, with the reasoning still readable afterwards — and a feel for when this is worth the effort and when it is not.
What you need: tutorial 02 finished, and 04 if you have not used comment threads yet.
What this is for
You have an idea. It is one sentence long and you are not sure it is right.
The two usual options are both bad. Talk it through with an AI and you get a good conversation that evaporates — next week you remember the conclusion and not the reason, and nobody else was there. Or write it straight into code, and the decision is now buried in a diff where the alternatives you rejected are invisible.
There is a middle: write the idea down as a document that argues with itself, get the open questions answered on the document, then act. More formal than a chat. Less formal than source control. The document is the artifact, and the reasoning survives in it.
Throughout this tutorial we will use one running example: a shopping list app that needs to let people reorder items by hand.
1. Start with the problem, not the solution
Make a folder called drafts/ and a file in it — manual-ordering.md.
The temptation is to write down what to build. Resist it for one section, and write what is wrong instead:
# Manual ordering for the shopping list
**Status:** draft · nothing built · this asks for nothing to be built until §5 is
answered
## 1. The problem
The list sorts alphabetically. That is a fine default and it is wrong in a shop,
because a shop has an order: produce, then chilled, then tins. A list sorted by
name makes you walk the aisles four times.
Two things are doing work there. The status line says nothing is built, so nobody has to guess how much of this is real. And the problem is described in terms of the person walking the aisles, not in terms of the code, which is what stops the next three sections quietly assuming a solution.
2. Say what you are not doing
This is the section people skip and then regret. A short list of non-goals, each with a reason:
## 2. Not doing
| Not doing | Why |
|---|---|
| Learning the order from past trips | Needs history we do not keep, and it would guess wrong for a new shop |
| Per-shop orderings | One order is enough to find out whether ordering helps at all |
| Sorting by category automatically | Categories are a data problem wearing an ordering costume |
The reason each line exists is that every one of them is a thing somebody will propose halfway through, and a written non-goal answers it in a sentence instead of a meeting.
3. Weigh the options, in the open
This is the part that makes a document worth reviewing. Not "here is the plan" — "here are the plausible approaches, and here is why the others lose."
## 3. Options
### A. A position number on each item — *recommended*
Each item carries a number; the list sorts by it. Dragging rewrites the numbers of
the items between the source and the target.
- Simple to read: the order is a column you can look at.
- Cost: a drag can rewrite many rows, and two people dragging at once can produce
the same number twice.
### B. A single ordered array on the list
The list owns an array of item ids in order.
- One field to write, so a reorder is one update and cannot half-apply.
- **Rejected:** an item can then exist in the list and not in the array, and now
there are two places that disagree about what is in the list.
### C. Fractional positions
Insert between 1.0 and 2.0 at 1.5, so a drag rewrites exactly one row.
- Genuinely elegant, and the reason to keep it in mind for later.
- **Rejected for now:** it trades a common cheap operation for a rare confusing
one, when the numbers eventually run out of room and have to be renumbered
anyway.
Notice that C is rejected without being dismissed. A future reader who wonders "why didn't they just use fractions" has their answer, and it is a real one. That is what a document can do that a diff cannot.
4. Write the scenarios as the contract
Before anything is built, say what "built" will mean. Number them, so a comment can name one:
## 4. Scenarios to test
Nothing is built; no ✅ appears here on purpose.
- **S1:** Given a list sorted alphabetically, When an item is dragged to the top,
Then it stays at the top after a reload.
- **S2:** Given two items with the same position, When the list renders, Then the
order is still stable rather than arbitrary.
- **S3:** Given an item is deleted from the middle, When the list renders, Then no
gap is visible and no reorder is needed to fix it.
- **S4:** Given a new item is added, When it appears, Then it is at the end rather
than alphabetically inside the manual order.
S4 is the one worth pausing on. It is not a requirement anyone stated — it fell out of writing the scenarios. That is why you write them before building: the awkward cases show up while they are still cheap.
Later, when each is covered by a test, put a tick on it. Then "built" is a claim with evidence rather than a status field somebody updated optimistically.
5. End with the questions you cannot answer alone
This is the section that turns a document into a conversation:
## 5. Decisions needed
1. **Does a new item go to the end, or alphabetically into the manual order?**
The end is predictable; alphabetical keeps some structure. S4 assumes the end.
2. **Should reordering be available on a phone?** It is the place you actually use
the list, and it is the hardest place to drag.
3. **What happens when two people reorder at once?** Option A can produce duplicate
positions. Refuse the second, or accept and stabilise?
Numbered, specific, and each one a real fork rather than a rhetorical question. A question you already know the answer to belongs in the body as a decision, not here.
6. Answer on the line that asks
Here is where the workspace earns its keep. Do not answer these in a chat.
Open the draft, select question 1, and start a comment thread on it. Write the decision there:
New items go to the end. Alphabetical-into-manual-order is the worst of both — you cannot predict where a new item lands, which is the one thing a manual order is supposed to give you.
Do the same for 2 and 3. Now the decision and the question it answers are in the same place, anchored to each other, and they stay anchored while the text around them is edited.
Six months from now the question "why do new items go to the end?" has an answer attached to the sentence that asked it. That is the property no chat log has.
7. Fold the decisions in, then promote
Mention your agent on the title of the document:
@helper-bot All three questions are answered in the threads on this file. Fold the decisions into the body, replace §5's open questions with the settled answers, and move this into
specs/.
The agent reads the threads, edits the document, and moves it. The draft becomes a spec — and "spec" now means something precise: a document with no open questions left in it.
That is the whole status model. Two folders, and which one a document is in tells you whether it is still being argued about.
8. Then build it
Now the agent implements it, and the scenarios in §4 are the checklist. Each one that gets a test gets a tick.
The reply lands on the thread, not in a terminal. The conversation about the work stays attached to the document that specified it.
When not to do any of this
Most changes do not deserve a spec, and pretending otherwise is how the practice gets abandoned.
The test is simple: is there a decision to make?
If there is a genuine fork — two defensible approaches, or a question only you can answer — write it down, because the reasoning is the valuable part and it is the part that gets lost.
If there is no fork, skip all of it. "The button is the wrong colour", "this label is misspelt", "add a path parameter to that function so it matches every other function" — these have one right answer and no alternatives worth recording. A spec for one of those is ceremony, and the time goes into writing a document nobody will ever reopen.
The other honest cost: a spec nobody re-reads is overhead. These are worth writing because agents read them at check-in and because you read them when you come back. That only holds if they stay true — a spec describing a version of the app that no longer exists is worse than no spec, because it is confidently wrong.
What you have now
An idea that survived contact with its own alternatives, decisions attached to the questions that prompted them, and a document that tells the next reader — human or agent — not just what was decided but what was considered and dropped.