jschoubben
8f9a6d4f7b
mesh/delivery closed: a newer head of the same pull request
mesh/check checking 8f9a6d4f7bc9 on b229f5c4df1e
Milestone 47/G was prepared and developed from a 430 KB design by agents told to start from the knowledge base and judge what was not mesh-shaped. The prepare wrote its own findings and about 40 rulings by two leads, seven of which went against the records or the design, and 29 questions the design never answered surfaced only in develop. The playbooks now make the milestone's part of its design the only input to the prepare, develop and the code review: the prepare outputs a build map per repository and the design questions; the operator answers each and the answer is written into the design before develop starts; every commit cites the design lines it builds and the review judges it against them. A design is a main file and one part per milestone, within a size an agent reads whole. Also: one lead per milestone, a contract's users start from its commit, one writer per file, one sibling placement, and agents stop between subtasks, never inside one. Claude-Session: https://claude.ai/code/session_01JG73KK8HD1gufnqyFxMFdW
89 lines
6.8 KiB
Markdown
89 lines
6.8 KiB
Markdown
# Playbook 04 — Work breakdown and handoff
|
|
|
|
**Trigger.** A to-be design is settled (playbook [02](02-graduation.md)) and its building is about to start.
|
|
|
|
**Who runs it.** The lead who will run the feature, on the larger model. It is one sitting, bounded at about
|
|
an hour, and said to the operator if it runs past.
|
|
|
|
## What it produces
|
|
|
|
A design becomes **milestones**, and each milestone becomes **issues**:
|
|
|
|
- **A milestone is usable on its own.** Once it is delivered, the operator or the mesh can do
|
|
something new, said in one sentence ("a Claude Code session is mirrored into a thread on the bus").
|
|
A milestone that changes nothing anyone can use is not a milestone; fold it into the next.
|
|
- **A milestone is one release** of playbook [07](07-feature-branches.md): prepared, developed whole, reviewed,
|
|
checked and delivered as one, never cut for its size or for time (the operator, 2026-10-17).
|
|
- **A milestone is one piece of functionality, never cut by an order between its parts** (the operator, 2026-10-21:
|
|
a milestone may span several modules, repositories and dependencies such as an SDK change; 2026-10-22: "a milestone
|
|
is a milestone, we shouldn't cut it"). Which of its modules reaches the machines first (a reader of a new manifest
|
|
word before the modules that use it, a provider before its consumers) is the assigner's rules' (design 47); an SDK
|
|
change is built into its users. The parts such an order touches are found in playbook [07](07-feature-branches.md)
|
|
step 0 item 6 and become issues of the same milestone; an order those rules cannot keep is an issue of the build
|
|
and delivery system, not a cut.
|
|
Until 2026-10-22 this rule cut milestones by release order (design 47's release 1-2 became six milestones).
|
|
- **An issue is one repository's part of a milestone,** sized so a fixing agent finishes it inside the
|
|
milestone's development time. Issues that must land in order are linked `depends-on`.
|
|
|
|
## Steps
|
|
|
|
1. **Confirm the design is settled.** Its frontmatter reads `status: designed`, and every claim in it traces
|
|
to a decision record in the knowledge base (`knowledge-base.get` for each entry of its `decisions:`). An
|
|
open question in the text is a reason to go back to playbook [01](01-research.md), not to build around it.
|
|
2. **Name the owners.** Set `code:` in the design's frontmatter to the repositories from
|
|
[`repos.md`](../repos.md). A repository that does not exist yet is added to `repos.md` in the same change.
|
|
3. **Check the as-is.** Read the matching `03-DESIGN/00-as-is/` document. What is being replaced is stated
|
|
there; if it is not, write it before changing it. Building against an undocumented as-is is how a shipped
|
|
behaviour gets lost.
|
|
4. **Break it into milestones.** Write them into the design, in a section *Milestones*: for each, its number,
|
|
its one-sentence outcome, the acceptance tests of the design it proves, the repositories it touches, and
|
|
what it depends on. Order them so each is usable as soon as it is delivered, the smallest useful one
|
|
first. A milestone is named by what it lets someone do; how it ships is shaped by the modules its changes move
|
|
and the nodes that run them (ADR 0401 §6), read from the indexer's fingerprints through the status view's
|
|
`indexer_modules` and `indexer_candidates`, and from the nodes' haves (`node_haves`).
|
|
4a. **Give each milestone its part** (playbook [02](02-graduation.md), *The shape of a design*): every line the
|
|
milestone builds moves from the main file into `NN-milestones/<milestone>.md`, as numbered design lines, each
|
|
naming what its builder needs. A milestone whose part would pass 60 KB is split here into two milestones, each
|
|
usable on its own; this is the one place a milestone is ever cut, for what one agent can read, before any work
|
|
starts. The main file stays within 80 KB. Written by `hq-design-writer` in the same change as the milestones.
|
|
5. **Ask the operator to confirm the milestones**, in a short table: number, outcome, the acceptance tests it
|
|
proves, repositories, the parts each repository builds. Change what they change.
|
|
6. **Open the issues.** For each confirmed milestone, `issue-tracker.open` one issue per repository part, its
|
|
title the symptom or capability in plain words, its report naming the design, the milestone and the
|
|
decisions it builds with; link the order with `depends-on`. Write the issue numbers into the milestone's
|
|
entry in the design.
|
|
7. **Flip the status.** `status: in-progress`, `updated:` today; the design change goes through playbook
|
|
[08](08-small-fixes.md) (one hq pull request).
|
|
8. **Hand each milestone to playbook 07, one at a time.** The milestone is one release of playbook 07; its issues
|
|
are the release's issues; the next milestone starts when the previous one is delivered. Playbook 07 builds from
|
|
the milestone part alone and starts its develop step only once that part answers every design question its
|
|
prepare finds (playbook 07, *Design complete*); a question is never answered by building around it. A design waits
|
|
while another design's milestones are being built: one design is built at a time (playbook
|
|
[07](07-feature-branches.md)), so this step starts only when the design before it is delivered.
|
|
9. **On completion of the last milestone**, run the "when something ships" section of playbook
|
|
[02](02-graduation.md).
|
|
|
|
## Rules
|
|
|
|
- What the handoff leaves for later is an issue with an owner, named in the design or the decision that leaves
|
|
it — never a sentence saying "later". The design's `code:` names who owns what is built; the issue names who
|
|
owns what is not. The knowledge base's rule `deferral` checks the decision record when it is proposed
|
|
([issue 354](../../04-ISSUES/354-a-decided-rename-was-never-scheduled-and-the-operator-believed-it-live/00-report.md)).
|
|
- HQ is not a code repository and never carries implementation.
|
|
- How the building is done — worktrees, agents, review, checks, the Approve and the delivery — is playbook
|
|
07's, not this one's.
|
|
|
|
## How it is checked
|
|
|
|
Read by the lead and the reviewer today; a check among hq's Go tests is tracked by issue 845.
|
|
|
|
- A design in `status: in-progress` has a *Milestones* section, each milestone with its outcome and its
|
|
issues; an in-progress design without one is the smell of building without a breakdown.
|
|
- Each milestone of an in-progress design has its part under `NN-milestones/`, within 60 KB, its lines numbered
|
|
(`ls -l 03-DESIGN/01-to-be/NN-milestones/`); a milestone handed to playbook 07 without one is step 4a skipped.
|
|
- Every issue a milestone names exists in the tracker (`issue-tracker.get`), and an issue in `fixing` names
|
|
its milestone in its report.
|
|
- A milestone whose issues are all `resolved` is delivered (the status view said `delivered` for its source
|
|
revision); its outcome sentence and
|
|
acceptance tests are proven on the mesh before the next milestone starts.
|