# 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 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.