mesh-tools
6be8f6eada
mesh/merge-gate head 6be8f6eada67 merged into trunk b7e22be7f55f — pass: [release feat/57-config-and-provisioning, judged by its controller cf897e89fe31] t…
mesh/repo-check head 6be8f6eada67 merged into trunk b7e22be7f55f — pass: [release feat/57-config-and-provisioning, judged by its controller cf897e89fe31] i…
mesh/delivery delivered
67 lines
4.4 KiB
Markdown
67 lines
4.4 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 its delivery plan is done, 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 feature step** of playbook [07](07-feature-branches.md): prepared, developed in one to
|
|
two hours, reviewed, checked and delivered as one. A milestone larger than that is split.
|
|
- **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.
|
|
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 the feature step; its issues are the
|
|
step's issues; the next milestone starts when the previous one's delivery plan is done.
|
|
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 ready mark 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 in hq's merge-check 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.
|
|
- 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` has had its delivery plan done; its outcome sentence and
|
|
acceptance tests are proven on the mesh before the next milestone starts.
|