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.

Related issues in one fix. A small fix may cover two or three related issues when they are in the same repository, mostly in the same module, and together still fit in about an hour: they touch the same files, or one would be wrong or unsafe without the other (switching a clipboard's history on before its history tool stops handing out what was copied). Each issue is named in the commit and the pull request and moved to fixing, and each is resolved on its own once the fix is delivered. More issues, a second repository, or more than an hour is a feature.

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 unit tests of what changed green (each well under a second; never a merge check or a database locally: how-we-build §5, ADR 0391). 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; a finding outside the issue's done-when is opened as an issue of its own, never asked as a change). 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 the branch, try it, then open the pull request. mesh-controller.try with the repository and the branch runs the merge check in the check's own toolchain before any status is set; open the pull request only once it passes. A local run never stands in for it: the check's containers carry other tools than the nodes (a test that called util-linux flock -E passed on a node and failed on BusyBox's in the check). 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. The reviewer marks it ready at once (mesh/ready and ready at <full sha>, the head it approved); mesh-delivery merges it when its checks pass. A fix to a module proves the issue's done-when with the module running whole (its process against a real bus and store) before it is marked, not with unit tests alone. The operator's word is waited for only when the fix changes what the operator sees, removes data, or needs the operator's terminal.
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.

A fix that stops before its delivery moves its issue back to open with a note saying how far it got (branch, last commit, what is left), as playbook 07 says.

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 ready mark	15 minutes after the review approved	the reviewer marks it, or the lead does
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.