jschoubben
464833d0ef
mesh/merge-gate head 464833d0ef3f merged into trunk 99a9da095010 — pass: the change touches no module of the mesh's graph
mesh/repo-check head 464833d0ef3f merged into trunk 99a9da095010 — pass: its merge-check.sh passed
mesh/delivery superseded: a newer head of the same pull request
A feature waited a day for its last issue, each small issue paid for its context again, and waits nobody saw cost the most time. The operator set the flow on 2026-10-15: prepared context per repository, one to two hours of local development on unit tests, one review of at most three rounds back to the same agents, one push for the integration checks, then the delivery plan; steps for a larger feature; a separate playbook for small fixes; models per step; a wait list with bounds; a prepared clear at each phase end.
58 lines
3.4 KiB
Markdown
58 lines
3.4 KiB
Markdown
# 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).
|
|
|
|
**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 2 rounds). 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.
|