# 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 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** (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, or a lab run, are not that proof. 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 opened with no passing `mesh-controller.try` on its head, one 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.