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](07-feature-branches.md).

**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, and the lead marks it ready on that word.
5. **Push once and open the pull request.** The forge's merge check runs the integration tests, the only
   place they run (the operator, 2026-10-16). 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** (for an edit that skipped the reviewer, the lead, on the
   operator's word) (`mesh/ready` and `ready at <full sha>`, the head it approved);
   mesh-delivery merges it when its checks pass. A fix to a module that changes how it runs carries an
   integration test starting the module whole against the real bus and store, run by the forge's checks
   (ADR 0391 §1, §6); unit tests alone are not that proof, and the lab is not used. 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](07-feature-branches.md) 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.
- A pull request reviewed and green but unmarked
  for more than 15 minutes, a fix to a module's running marked ready with no integration test of the module whole, or a review report
  asking a change outside the issue's done-when, is the failure of steps 4 to 6.
- An issue in `fixing` with nobody on it shows in `issue-tracker.list` with `flag: abandoned`; a stopped fix
  moves it back to `open` with its note.