Refine: Tick It Off, Write It Down, Move On

Step 7 of 7.

The branch is merged. The easy ending is to move to the next task. This step does two small things first: it ticks the task off, and it writes down what the team learned. Then, sooner or later, it meets a harder case: the team learns something that changes a decision.

Our goal: close a feature properly, and see one real lesson go back into the documents, in the right order.

Here is the route:

How a team closes a ticket, and what a retrospective is for.
Tick it off and start fresh.
An example: money should not be a double.
Documents first, then code.

We leave out running the retrospective as a team meeting, and shipping to a server.

How a team closes a ticket

When a ticket is done, a team does two things. It moves the card to "Done", so everyone can see what is left. And now and then it holds a retrospective: a short look back at what went well, what hurt, and what to change. "We keep forgetting to run the checks before review" becomes a line in the team's working agreement, and the next ticket goes better.

An AI team needs both, and the second one is more useful than it sounds. The agent forgets everything between sessions (lesson 02). What the team learned only survives if it is written down.

Tick it off, and start fresh

After the merge, three small things:

Tick the task in docs/tasks.md, so the list shows what is left. Ticking is the proof that it was built, tested and approved.
Delete the branch, since its work is now on the main line.
Start the next task in a new session, a new hire again. The pointer file brings it up to date, and the ticked list tells it where you are.

Do not carry one long session across tasks. It fills with old details, and the agent's attention to your instructions thins out (lesson 01).

An example: money is not a double

A few weeks in, the team's Conventions in the README (lesson 08) carry a line: "money values use double". It looked reasonable when it was written, because double is the usual type for a number with a fraction. The agent follows the Conventions (that is what they are for), so every price in the bookshop is stored as a double.

The tester adds up the prices of a few books and the total is a cent out. The team looks into it. A double keeps a close approximation in binary, which is fine for a measurement and wrong for money.

A decimal keeps exact decimal digits and is meant for money. The team agrees: all money is a decimal. Nobody was careless. The AI followed the written convention, and the convention was the thing that was wrong. That is lesson 02 from the other side: an AI is only as accurate as the guidance it gets. So the fix starts in the guidance.

If the code changes first, the README still says "use double". A fresh session reads it, obeys it, and puts the bug back. So change the documents first (rule 1).

1. The README. Replace the old convention with the decision, and the reason:

<!-- before -->
- Money values use double.

<!-- after -->
- Money is a decimal, never a double. A double is approximate, so
  prices and totals drift by a fraction of a cent.

2. The specs. Spec 03 gets a rule and a check, and the agent is asked to look at the other specs too:

**Rules**
- The price is a decimal with two places.

**Done when**
- A price of 19.99 is saved and shown as 19.99.

3. The agent changes the code. On a new branch, with a short request:

Money is now a decimal, see Conventions in README.md. Find every place a
price is stored or calculated with a double, change it to decimal, and
update the tests. Do only that.

Finding every place is what an agent is good at. Steps 5 and 6 apply again, as for any change: the tests run, and a person reads the diff.

4. Rule 2. The bug taught the team something, so it is now in the README. The next session starts from it, and so does the next hire. Other lessons go the same way: one line, in the right place. A habit the agent keeps getting wrong goes under "We avoid" in the README. A wrong build command goes in the small file (lesson 10). Something that must never happen becomes a deny rule.

Where we ended

The decision is in the documents, and the code agrees with it.

Before (the end of lesson 13): the README says money values use double, and the code follows it for prices.

After:

bookshop-backoffice/
├── README.md                  <- changes  the money convention replaced
├── CLAUDE.md
├── .claude/settings.json
├── docs/
│   ├── tasks.md               <- changes  task 03 ticked
│   ├── specs/
│   │   └── 03-add-book.md     <- changes  a rule and a "Done when" line for price
│   └── review-requests.md
├── src/                       <- changes  price is a decimal
└── tests/                     <- changes  tests use decimal

A checklist for your own project

This is the whole course on one page. Take it to a small project first.

Before any code

Talk the problem through with the AI and decide. Write the decisions down, with the reason for each (the README).
Write the conventions: what the team likes and avoids. Start with two or three.
List the tasks in order, smallest first, and write a short spec for each as a batch: goal, behaviour, rules, out of scope, done when.

For each task

A fresh session, and a new branch created first. The plan before the code.
Check the result against the "Done when" lines. Tests from the spec, and reviews with one hat per pass.
A person reads the diff and approves before anything is pushed.
Tick it off, and write what you learned in the right place.

Always

A change of plan goes into the docs first, then the code. What you learn goes back into the docs.
Start the agent on ask-first, and loosen it only as you learn.
Keep each task small enough to read in one sitting.

An AI is only as accurate as the guidance it gets, and a person still owns the result. Tools will change. This process is the part that lasts.

Recap

A team ticks a ticket off and now and then looks back. For an AI team the look back matters more, because the agent forgets and only the documents remember.
After a task: tick it off, delete the branch, and start the next in a new session.
When the team learns that a convention was wrong, change the documents first, then the code and tests (rule 1). The AI followed the old line, so code first lets the bug come back.
The agent can find every place to change. Steps 5 and 6 still apply to that change.
Rule 2 in one line: the lesson goes into the right document, and the next session starts better.
The whole process fits one checklist: decide and document, spec a batch, then for each task a branch, checks, a person's read, and a line written back.

Questions to think about

The answers are left out on purpose. Try them in your own words first.

Why does an AI team need to write its lessons down more than a human team does?
Why start the next task in a new session?
Why was the AI not at fault for using a double?
When the team decides to change something, why write it in the documents before changing the code?
What makes a good line to add to the documents?

This is the last lesson. Take the checklist to a small project of your own.