hq/00-META/process/08-small-fixes.md

Playbook 08 — Small fixes

Trigger. One issue in one repository, small enough to build in about an hour: a bug with a known cause, a missing check, a wording, a playbook or design edit. Anything larger, or anything that needs a change in a second repository first, is a feature and follows playbook 07.

Who runs it. Anyone who writes code, engineers and agents alike.

The aim

A small fix spends its time on the fix, and runs the long part once: one review, one push, one check run, one delivery. Everything before the push is local and fast.

Steps

1. Read the issue and the code it names (the session's own model, or one read-only agent on the smaller model answering exact questions with file:line). If a design question is open, it is settled before any code is written: on the issue, through the knowledge base, or by the operator. A fix that turns out to need a decision or a second repository stops here and becomes a feature.
2. Move the issue to fixing with by as who@node.
3. Build on a local branch fix/<issue>-<slug>, in a worktree of its own branched from main. Write the test that fails today first; make the change; keep gofmt, go vet and the repository's unit tests green. Commit, naming the issue. For a playbook or design edit, run the repository's own checks (in hq, sh merge-check.sh).
4. One review of the local commit, before anything is pushed (a reviewer that did not write it, larger model; at most 3 rounds, as playbook 07; from round 2 only what is wrong). The reviewer's findings go back to the same agent that wrote the fix, continued by its id, so the fix keeps its context. A playbook or design edit of a few lines may skip the reviewer: the operator's word on the pull request is its review.
5. Push once and open the pull request. The forge's merge checks run the integration tests. A failed check goes back to the same agent with the failure, and the reviewer reads only the change it makes.
6. Mark it ready (mesh/ready and ready at <full sha>) once the operator's word is given; mesh-delivery merges it when its checks pass.
7. Follow its delivery plan to done (mesh-controller.plans with wait and until: done), prove the fix on the mesh (the symptom gone, measured), and resolve the issue with located-in and fixed-by the same hour.

Bounds

Waiting on	Bound	Past the bound
building the fix	1 hour	it is a feature: stop and plan it under playbook 07
the review	15 minutes	ask the reviewer where it stands
the merge check	15 minutes	read mesh-controller.queue and the check's log
the merge after ready	5 minutes after the checks pass	read mesh-delivery.show for the delivery
the delivery plan	its class's budget (mesh-delivery.times), at most 30 minutes	read mesh-controller.plans, then mesh-delivery.stalled

A wait past its bound is said to the operator at once, with what is being done about it.

Models

The fixing agent runs on the smaller model; the reviewer on the larger. A session fixing alone does the reading itself and uses one subagent only for the review.

How it is checked

• A small fix has one pull request with one or few commits naming its issue, opened after its review: a pull request with many heads is a fix reviewed after its push.
• Its issue moves to resolved within the hour its delivery plan ends.