bolt-planning

Files (1)

• SKILL.md

SKILL.md (first lines)

# Bolt planning — one planning run

You compute the system's remaining work and propose how to cut it.
You do not build anything, and you decide nothing the operator has
not asked you to decide: your product is plan documents, and every
plan waits for board approval before anything else exists.

## Inputs — read all three, nothing else

The work order names the design book and the built repo.

1. **The design book, whole.** Every chapter. The destination is
   stated across chapters — synthesize; a single task may draw on
   several. Record the book's subtree commit
   (`git -C <book> log -1 --format=%h -- .`).
2. **The implemented specs** — `openspec/specs/` in the built repo:
   what the repo actually does today. Record the specs subtree commit
   (`git -C <repo> log -1 --format=%h -- openspec/specs`).
3. **The changes in flight** — `openspec/changes/` in the built repo:
   what is already being built. Never plan work a change in flight
   already covers, and never contradict its sequencing.

The gap is destination minus implemented minus in-flight. If the work
order scopes the run ("the smallest useful bolt", "a bolt about X"),
the scope limits which cuts you propose, not how carefully you read.

## Cutting the gap into a bolt of units

Two levels, two different objects:

- A **bolt** is the operator's delivery boundary: one milestone, one
  branch, one landing to main. It lives for days and absorbs several
  units. Propose ONE bolt per run unless the gap genuinely splits
  into independent deliveries — many small bolts is the failure mode
  this shape exists to avoid.
- **Name the bolt for the deliverable the operator wants to see
  working together, never for the work items that build it** — a bolt
  named for its tasks is a to-do list wearing a milestone. This rule is
  every plan author's, not only this run's: dispatch plans and dictated
  cards cite it from here.
- **Read the open `bolt/*` milestones before proposing a new one.**
  Units that serve an open bolt's deliverable fold into it as new
  cards; a related idea splits — the parts the open bolt's deliverable
  needs go in as units on it, the harder or independent parts become a
  proposed successor bolt. A new bolt is for a new deliverable, not for
  new work.
- A **unit** is one coherent batch inside the bolt: buildable in one
  pass of the construction loop, leaving the branch consistent.
  Prefer small units inside one bolt over many bolts.
- Sequence units by dependency and by risk: what unlocks the rest
  comes first. State the order and the reason for each boundary —
  what you left for a later unit, and why.
- A dependency exists on exactly three grounds, and you name which:
  **derivation** (this work's specs derive from specs another task or
  unit advances at its merge), **contention** (two tasks would write
  deltas to the same capability — chain them or fold them into one),
  or **runtime precondition** (the behavior needs an artifact the
  other work produces in the world). Anything else is independent; a
  chain without one of these grounds serializes work for nothing.
- Every task cites the chapter or chapters it derives from, by path
  (`books/<book>/src/<chapter>.md`). A task you cannot tie to a
  chapter does not go in a plan — if the code clearly needs work the
  book never describes, report that as a question for the operator
  instead: the book is silent, and silence is a design gap, not a
  license to invent.
- **A unit is a proposal to a system, written from the user's
  perspective.** Name it and open it as the feature or capability a
  user of the system gains, not as the internal mechanism that
  delivers it. The book's sentences justify the unit; the user's
  story shapes it.
- **Size each change by how much code it actually is, never by how
  many book sentences it serves.** If several claims would be
  implemented together as one small commit, make them one change, not
  several. Every change costs a full loop cycle — a spec session, a
  review, a build session, verify, a merge — so splitting is only
  worth it when a piece has its own tests, a real dependency on
  another piece, or lives in a different repo. Four changes for four
  lines of code is the failure this rule exists to stop. Before
  delivering, reread each unit and ask of every pair of changes:
  would these be one commit in one repo? If yes, merge them into one.
- **Different repos do mean different changes.** A system's book may
  cover several built repos; a unit that touches more than one then
  needs one change per repo, because each repo runs its own
  spec-driven change through its own merge gate. The unit stays whole
  — it is still one user-facing proposal — but the work splits along
  repo lines and nowhere else. A one-repo system gets no such split.

## The chore tier — below the ceremony line

Some of the gap is work with **no new behavior**: deleting dead code,
correcting a docstring or comment that lies, stamping a superseded
draft's header, renaming or moving a file, fixing a label or status.
The agent that finds such work already knows exactly what to do, and
the operator's whole decision is yes or no — so a chore NEVER gets a
unit document. An essay, a mermaid diagram, or destination-voice
framing around a two-line diff is the failure this tier exists to
stop: it spends the operator's minutes decoding ceremony around work
that needed none.

All the chores a run finds for one system collapse into **one chore
card**: title `Unit: chores` (the `chore` LABEL marks the tier — the
title keeps the grammar the loop parses), labels `plan` + `chore`,
filed on the open bolt they tidy (or the run's proposed bolt) exactly
like any card, body in this grammar and nothing more:

```markdown
# Unit: chores

System: <name>
Type: `chore` · Price: <n> changes · ~hours

| # | change | delivers |
|---|--------|----------|
| 1 | <short-name> | <one plain line — the whole instruction> |
```

No sequence line, no mermaid, no Left out, no derivation footer. A
chore needs **no chapter citation** — its justification is that it
makes the code or docs true, not that the book demands it. `chore` is

From agentplot/flywheel, MIT.

More from agentplot/flywheel