4.1 KiB
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
- 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.
- Move the issue to
fixingwithbyas who@node. - Build on a local branch
fix/<issue>-<slug>, in a worktree of its own branched frommain. Write the test that fails today first; make the change; keepgofmt,go vetand 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). - 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.
- 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.
- Mark it ready (
mesh/readyandready at <full sha>) once the operator's word is given; mesh-delivery merges it when its checks pass. - Follow its delivery plan to done (
mesh-controller.planswithwaitanduntil: done), prove the fix on the mesh (the symptom gone, measured), and resolve the issue withlocated-inandfixed-bythe 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
resolvedwithin the hour its delivery plan ends.