pipeline git:20260908.deb49c9A

Immutable. This exact content never changes and is served at /api/v1/blob/edf006c7042f9ae7.

---
name: pipeline
description: Use when the user wants a feature idea taken end-to-end in one autonomous run — phrases like "run the whole pipeline", "take this feature from idea to finished branch", "brainstorm then build it autonomously", "do everything from idea to merged", "implement all phases without stopping". Triggers when they want brainstorm → plan → implement → review → fix chained with minimal supervision.
argument-hint: "[resume|status]"
---

# Superpipeline

## Overview

`pipeline` drives a feature from idea to a finished branch by **composing
existing superpowers skills** — it never reimplements brainstorming, planning,
or review. It calls those skills and manages the seams between them, plus an
autonomous per-phase implement → review → recursive-fix loop.

**The one exception is implementation dispatch**, which this skill owns
(`references/implement.md`). Every available implementation skill accepts a
task only against a review it dispatches for that task, which is a second
acceptance gate for work this skill accepts at the **phase** — so composing one
reviewed every phase twice. Owning the dispatch is what makes the invariant
mechanical: completing a task dispatches no reviewer.

**Core principle: compose, don't reimplement.** Every stage delegates to the
canonical skill for that job. This skill's only original logic is the
orchestration: the zero-assumption rule, the on-disk run state, the gates, the
reviewer fan-out math, and the fix loop.

**Reference files** — read at the stage that needs them:
`references/run-state.md` (file formats, task-line grammar, cold-start resume,
dispatch contract), `references/implement.md` (Stage 4's IMPLEMENT state: how a
phase's tasks are dispatched, waved and merged, and why completing one
dispatches no reviewer), `references/fix-loop.md` (Stage 4's loop and guard
rails) and `references/parallel.md` (Rule 6: dependency annotations, waves,
lanes, worktrees and merges, and the Brain-Agent mode).
`templates/` holds the run-state file templates.

## Invocation

Dispatch on the argument below, before doing anything else. An empty argument
means Full mode. Ignore any whitespace around the argument.

`$ARGUMENTS`

That is the whole argument string. **Never key this table on an indexed
placeholder.** `\$0` is the first positional argument and it does get substituted —
but an indexed placeholder with no argument at its position is left in the prompt
verbatim, so a bare invocation renders a stray literal `\$0` into exactly the arm
this table calls "no argument". `\$ARGUMENTS` expands to the whole argument string
as typed, so it has no such hole. Every mention of a placeholder in this file that
is *not* the dispatch target above is backslash-escaped for that reason: an
unescaped one would be substituted too, and would rewrite the very text that
documents it.

| Invocation | Behavior |
|------------|----------|
| `/superb:pipeline` (empty `\$ARGUMENTS`) | **Full mode** — start at Stage 1, step 0. |
| `/superb:pipeline resume` | Run the **Resume Protocol** in `references/run-state.md`. **Never start a new run in this mode** — if no run directory exists, say so and stop. |
| `/superb:pipeline status` | **Strictly read-only report** (below). No writes, no dispatches, no fixes. |
| `/superb:pipeline <anything else>` | **Ask the user what they meant.** Never guess a verb. `fix-mode` in particular is internal-only — set exclusively by this skill's own fix loop, never a user argument; if the user passes it, refuse and explain that. |

**`status`:** locate the run directory (same candidate logic as the Resume
Protocol — if more than one qualifies, ask which); read `progress.md`,
`register.md`, `findings.md`; and report:

- the Current State block;
- per-phase task counts (`[x]` / `[~]` / `[ ]`);
- **every phase's `RV` state, and any `RVJ`** — an open `RV` under a phase whose
  tasks are all `[x]` is the headline of the report, not a footnote: that phase
  was implemented and never reviewed;
- open register entries;
- open blocking F-IDs;
- fix-loop iteration counts from the Counters table.

Read-only means read-only: no tracker updates, no `[~]` reconciliation, no
dispatches, and no fixes — **not even "obvious" ones**. A fix is a run;
`status` is a glance. If the report surfaces something that needs work, say so
and let the user invoke `resume`.

## The Zero-Assumption Iron Law

```
NEVER ASSUME. EVERY UNKNOWN BECOMES A USER QUESTION.
```

The user who runs this pipeline has explicitly chosen exhaustive questioning
over speed. There is **no cap on question rounds** and no such thing as too
many questions. Asking again is compliant behavior; assuming is the only
failure mode. **Violating the letter of this rule is violating its spirit.**

- Applies at **every** stage — including the autonomous Stage 4 (see the
  Ambiguity guard below).
- User pressure — "I'm busy", "keep questions minimal", "use your judgment",
  "industry standards", "I trust you", "just show me something" — changes the
  **format** of questions (batch them into one compact round, give each
  question selectable options with a recommended default), never whether an
  unknown gets asked. Busy users get efficient questions, not assumptions.
- The decision predicate: **if the user's answers, the approved spec/plan, or
  a written repo rule states the answer → follow it. Otherwise → ask.**

### Assumptions Register (mandatory artifact)

From Stage 1 onward, every unknown and every default you were tempted to pick
is a numbered entry in **`register.md` in the run directory** — a file, not a
memory. Format in `templates/register.md`. Rules:

- An entry is closed **only** by an explicit user answer to **that entry**,
  recorded verbatim in the file. A register that lives only in context is lost
  to the next compaction, and "I'm sure they answered that" is not a closure.
- Bulk replies close zero entries: "approved", "go", "looks good", "proceed"
  do NOT confirm open assumptions. Forbidden shortcuts: "veto by exception",
  "silence = consent", "corrections to some items = approval of the rest",
  "reply one word to accept all defaults".
- **No gate may be presented while any register entry is open.** Ask the open
  entries as questions first; present the gate only when the register is empty.

## The Run State Law

```
THE FILES ARE THE TRUTH. YOUR MEMORY IS NOT.
```

Every run keeps its state **on disk**, in one run directory, and that state is
authoritative. Whenever a file and your recollection disagree — which phase you
are in, which tasks are done, which findings are open, which assumptions the
user actually answered — **the file wins, every time.** You do not re-derive
state from the conversation; you read it.

**A compact is where this law gets tested.** Whatever is true only in the
conversation dies there, so it has to be on disk *before* the context is
discarded — see *Compacting at GATE 2*.

```
<PROJECT_DIR>/docs/superpowers/runs/YYYY-MM-DD-<topic>/
  progress.md        # the tracker — phases, tasks, Current State
  register.md        # Assumptions Register
  findings.md        # blocking ledger (F-IDs), iteration history, deferred Minors
  kit.md             # the run's shared verification apparatus (written at GATE 2)
  agent-output/      # one file per dispatch; long subagent output lands here
```

**Formats, task-line grammar, the resume procedure and the dispatch contract
are in `references/run-state.md`. Read it at Stage 1 step 0.** Templates for
the templates ship in `templates/` and are **read-only** — copy them, never
edit them.

- **Run state NEVER goes in the skill directory.** A skill directory is shared
  across every project and every run; state written there corrupts the next run
  and leaks one project's work into another. If the path you are about to write
  to is inside a skill directory, or is not under
  `docs/superpowers/runs/<this run>/`, **stop — you have the wrong path.**
- **One run directory, created at Stage 1**, its full path stated to the user
  in your first message and reused verbatim for the rest of the run. Fix-mode
  recursions inherit it and never create their own.
- **If the directory already exists, that is a user question** — resume, start
  fresh, or abort — never a silent overwrite and never a silent resume. Show
  the user the existing Current State so the choice is informed.
- **Never `git add` a pipeline runtime directory — anything under
  `docs/superpowers/runs/*/`.** `progress.md`, `register.md`, `kit.md`,
  `findings.md`, fix plans, `agent-output/`, review reports: that is **ephemeral
  execution state**, it belongs on disk for the run and for a resume. This
  repository's root `.gitignore` carries `docs/superpowers/runs/*/` and a gate
  holds it there; in a project without that line the rule is yours to keep, and
  adding the line is the first thing to do. **Curated permanent documentation may be
  deliberately committed** — `docs/superpowers/specs/*.md`,
  `docs/superpowers/plans/*.md`, and loose `docs/superpowers/runs/*.md`
  records — when someone decides it is repository documentation. *May* is the
  whole of the permission: nothing auto-commits it.

  ```
  runtime directory          = forbidden
  curated permanent document = intentional, deliberate exception
  ```

  Plan around the consequence for the runtime half: none of it survives a fresh
  clone or a lost machine. **What has to outlive the run goes into durable
  artifacts** — the commits themselves, and the Stage 5 hand-off (which is why
  Stage 5 carries the design summary and the deferred-Minors table rather than
  pointing at these files).

"Phase" below means **both** levels: the pipeline Stages 1–5, and each
implementation phase of the expanded plan inside Stage 4. Every rule applies at
both.

### Tracker structure (fixed)

```markdown
# Pipeline — Progress Tracker

## Current State
- **Lane A:** <phase id FIRST, then that lane's next unchecked line — task, RV,
  or RVJ>
- **Last updated:** <timestamp>
- **Run directory:** <path>

## Phase 1 — <name> · deps: none · lane: A
- [x] T1 — <task name> · W1 · deps none — `a1b2c3d`
- [~] T2 — <task name> · W2 · deps T1 — started <timestamp> in `wt/p1-t2`
- [~] T3 — <task name> · W2 · deps T1 — started <timestamp> in `wt/p1-t3`
- [ ] T4 — <task name> · W3 · deps T2, T3
- [ ] RV — review fan-out
...
```

Every task line carries its **wave** (`W<n>`) and its **deps** (Rule 6); every
phase heading carries the phases it depends on (`· deps:`) and the lane that
executes it (`· lane:`). Tasks in the same wave may be
`[~]` at the same time — one of two sanctioned cases of more than one `[~]`
line (the other is concurrent lanes, each of which may hold its own `[~]` task
or `RV`), and each still gets its own write before its own dispatch.

### The RV line — review is a tracker line, not a memory

**Every implementation phase ends with an `RV` line**, written in at GATE 2 with
its task lines. (Only implementation phases — the Stages 1–5 seeded at Stage 1
are scaffolding and carry none.) It obeys Rule 2's write-before-work and Rule 4's
reconciliation, carries no `W<n>`/`deps`, and is **not a task**: it never counts
toward Rule 3's 12-task cap nor toward `N` in `ceil(N/5)`.

```markdown
- [ ] RV — review fan-out
- [~] RV — review fan-out · N=8 → 2 slice + 1 integration · started 2026-09-01 14:31
- [x] RV — review fan-out · N=8 → 2 slice + 1 integration · boundary: the T3 contract consumed by T7
      · reports p3-review-{a,b,int}.md · coverage p3-coverage.md → F-012, F-013
- [x] RV — review fan-out · N=8 → 2 slice + 0 integration · no integration boundary
      · reports p5-review-{a,b}.md · coverage p5-coverage.md → no findings
```

The `[ ]` form carries nothing else: at GATE 2 no task has a hash, and the
slice count is not yet written even though `ceil(N/5)` already determines it.
Both are filled in at dispatch.

**Closing it takes artifacts, not adjectives** — these fields, each checkable by
someone who was not there, all paths relative to `agent-output/`:

| Field | What it must satisfy |
| --- | --- |
| `N=<tasks> → <s> slice + <i> integration` | Which number `s` must match depends on the regime, and the declaration's own key says which — the regimes are the table below. Whichever one sized it, **`i` is 0 at one slice** — that slice already sees the whole diff, so a second reviewer over it is duplication a boundary cannot license. **Above one slice `i` is 1 only at a declared integration boundary**, named on the round as `· boundary: <what>`: a Rule 3 split's siblings joining, two lanes joining, or a contract introduced in one slice and consumed in another that no single slice's range covers. Otherwise `i` is 0 and the round says so (`· no integration boundary`) — an omission and a judgement read identically, and that is how a review goes missing without anyone deciding to skip it. |
| `fixplan <file>` | Fix rounds only: **required on a round declaring `M=<m>` with `m >= 1`**, absent from an `M=0 → no round` record. The round's fix plan (`templates/fix-plan.md`), written before the first fix was dispatched — findings → fix plan → fix implementation, in that order. A round that fixed something and names no plan is a round whose fixes nobody can check against a scope. |
| `coverage <file>` | One file holding **the slice assignment table above the `git log --oneline PB..PH`**, and ending with the verdict line `COVERED: <n>/<n> commits`. All three: a bare log is the input to a coverage judgement rather than the judgement, and a table with a gap in it sits above the log just as happily as one without. Anything short of `<n>/<n>` does not close the line. The table's own shape is fixed, below the regimes. |
| `→ <F-IDs>` or `→ no findings` | What the round produced. |

**Which regime sized the round — and whether the line proves it.** Every `N=`
row is re-derivable from the line; the others say so rather than borrowing that
guarantee.

| Key on the line | `s` is | Re-derivable from the line? |
| --- | --- | --- |
| `N=<n>` | `ceil(N/5)` | **Yes.** That is what `N` is on the line for: the fan-out is re-derivable at closure instead of trusted from the step that gets skipped. |
| `N=<n> W=<w>` | `ceil(N/5)` — **unchanged**, because `W` is informational | **Yes.** `W` records how many implementation waves ran, for history; it never enters the arithmetic. Implementation scheduling must not reduce formal review coverage. |
| `M=<m> C=<c>` | `c`, the file clusters in the fix diff | **As a declaration only.** `C` makes the sizing auditable and an arithmetic slip between the two numbers red, without establishing the count itself. `M` sizes nothing. |
| `RVJ` | always `0 slice + 1 integration`, its `N` informational | **Yes**, from the form. |

What a re-review round's fan-out *is* checkable against is its own `coverage`
table, where two reviewers over one cluster show up as two rows carrying the
same range.

**The coverage table's shape is fixed**, because the round's own arithmetic is
read off it and a later reader re-runs it: every row is **keyed by its report
filename, with that reviewer's exact range in the row's second cell, and every
report file the round names has a row of its own** — a reviewer with no row
has no recorded range for anyone to check any other against. And **no two rows
carry the same range**: two reviewers over one range read the same diff, and
the integration reviewer's row is the union of the slices, so it equals no
single slice's.

**The line's shape is machine-checkable, and only its shape.** The superb
plugin's own repository ships a linter for this grammar: from a checkout of
that repo, `./tools/check-plugin.sh --run <run-directory>` reads the tracker's
closed `RV`/`RVJ` rounds and names any whose declared count and listed report
files disagree, whose `N=` slice count is not `ceil(N/5)`, whose
integration count does not follow its slice count, whose `RVJ` is not
`0 slice + 1 integration`, whose `M=` declares no `C=<n>` or a `C` its slice
count contradicts, whose `coverage` field is absent, whose named report or
coverage files are not in `agent-output/`, whose coverage table (on a round of
two or more slices) leaves a named report without a row or gives two reviewers
the same range, or whose `M=0 → no round` record carries reviewer evidence.
It is not in a project's own tree unless that project is the plugin, so it is
a check a run can use, not a gate every run passes — Stage 5 is what runs it,
and says in the hand-off what came back.

**On an `M=` re-review round it still cannot check that the fan-out was
sized right**, and half of that will never be checkable from the tracker: the
duplication half is caught, since two reviewers handed one range are two rows
the linter can compare, but the count itself is not derivable from the line
there — `C` is on it as a declaration by whoever chose `s`, so one reviewer over a seven-cluster diff writes `C=1` and
passes.

**Every field is per round, and re-review rounds append their own.** The counts
are read against the round they sit in, never against the whole line:

```markdown
      → round 2: M=9 C=1 → 1 slice + 0 integration · fixplan p3-fixplan-r2.md
        · reports p3-rr2-a.md · coverage p3-rr2-coverage.md
        → F-012 closed, F-014 raised
```

The fan-out is **one reviewer per file cluster in the fix diff**, integration
only above one reviewer — not `ceil(N/5)`, since fix diffs are not task-shaped,
and not a count over the findings, since findings are not diff surface — with
coverage over the fix commits. Whoever ran the round writes it, at whatever
recursion depth.

**`M=0 → no round` is the one round that closes without reviewers.** `M` — the
targeted-F-ID count, less every one closed by a route that leaves no ownable
commit — is defined **once**, with the closed list of those routes, in
`references/fix-loop.md`, fix loop step 3. Read it there; a second copy of a
closed list here is a copy that can drift into being a shorter one. A fix
iteration whose `M` comes out zero runs no fan-out — and it still writes its
round, because an absent round and a skipped one are the same absence here:

```markdown
      → round 4: M=0 → no round · closures: F-021 withdrawn → malformed,
        F-022 withdrawn → superseded by F-013 → no findings
```

`no round` stands where the reviewer counts would, and `M=0` is the only
declaration that licenses it. In place of `reports` and `coverage` the round
carries each F-ID it closed and that F-ID's route, taken from the closed list
in `references/fix-loop.md`, fix loop step 3, and matching that F-ID's
`Closed by` cell in the ledger. `pinned by <test>` cannot appear here: a pin
commits a test, so it stays in `M` and its commit is owed a reviewer.
One behavioural fix, or one pin, in the same iteration makes `M > 0`, and then
the full fan-out is owed.

The one other closure: `[x] RV — WAIVED by user: "<their words>"`, which needs
those words verbatim in `register.md`, applies only to the phases the user named
(if that is unclear it is an Ambiguity stop, not a guess), and is listed in the
Stage 5 hand-off. To un-waive, set it back to `[ ]`.

**A phase whose `RV` is not `[x]` is not complete, however many of its tasks
are.**

**`RVJ` — the joint review of a designed unit.** A Rule 3 split, and a phase whose
deps span two or more lanes, each owe a review no single phase's `RV` can cover.
Same grammar and closure rules. It is always `0 slice + 1 integration` — one
reviewer, seeing the unit whole — with `N` = the tasks across that unit, and a
discriminator **naming the phases whose combined diff was reviewed**, since one
phase can owe two and "lanes A+B" is not something a third party can check:

```markdown
- [ ] RVJ — joint integration review · split 4a+4b
- [x] RVJ — joint integration review · lanes A+B (phases 5, 6) · N=17 → 0 slice + 1 integration
      · reports j-56-int.md · coverage j-56-coverage.md → no findings
```

It gets **its own Counters row**, its own appended fix rounds, and it sits where
it must be satisfied: after a split's last sibling (a **trailing** `RVJ`), above
the first task of a joining phase (a **leading** `RVJ`). Full procedure in
`references/fix-loop.md`.

**Closing a gate is not accepting a phase.** Call the gate a fix loop belongs to
its **`review_gate`** — an `RV` for a phase's own review, an `RVJ` for a split's
or a lane join's. The loop is the same whichever it is:

```
review_gate → findings → FIX_PLAN → FIX_IMPLEMENT → RE_REVIEW(review_gate)
            → clean → CLOSE(review_gate)
```

`CLOSE(review_gate)` is the generic terminal. `PASS` is **phase acceptance**, and
only a phase's own `RV` produces it — so what a closure unlocks depends on which
gate closed:

```
CLOSE(RV)              → phase PASS
CLOSE(trailing RVJ)    → NEXT PHASE
CLOSE(leading RVJ)     → IMPLEMENT JOINING PHASE
```

```
A CLEAN LEADING RVJ MUST NEVER MARK THE JOINING PHASE PASS.
```

A **leading** `RVJ` gates *entry*: it reviews the lanes that merged into this
phase, not this phase's own tasks, so after it closes the joining phase still
owes the whole of `IMPLEMENT → RV → CLOSE(RV) → PASS`, and the non-surviving
contributing lanes retire. A **trailing** `RVJ` closes a Rule 3 split and the
run advances past it. An `RVJ` is not a phase gate and never stands in for one.

**A round is appended under its own gate's line.** An `RVJ`-owned round is
ordinary — an `M= C=` fix round sized from the fix diff — and it hangs under the
`RVJ`, never under a joining phase's `RV`:

```markdown
- [x] RVJ — joint integration review · split 4a+4b · N=17 → 0 slice + 1 integration
      · reports j-4ab-int.md · coverage j-4ab-coverage.md → F-031
      → round 2: M=1 C=1 → 1 slice + 0 integration · fixplan j-4ab-fixplan-r2.md
        · reports j-4ab-rr2-a.md · coverage j-4ab-rr2-coverage.md → F-031 closed
```

The **Current State** block stays at the very top so re-orienting costs one
read and nothing else. Never move it below the phase lists, never split it,
never let a lane point at a line that isn't the first unfinished one of its own
phases — or, when that lane has none, at one of the two phase-less forms `done`
and `waiting at join Phase <id>` (`templates/progress.md`). Timestamps
come from a real clock (`date`), never from your sense of elapsed time.

**A lane line names the next unchecked line of that lane's phase, and an open
`RV` is such a line.** When the last task of a phase lands, the lane's next
action is that phase's `RV` — never the next phase's first task. Writing the
next phase there while `RV` is open makes the tracker itself instruct the run
to skip review, and the tracker is the thing every rule here tells you to obey.
**A lane may only name a phase its own `· lane:` carries**, and a sequential
run has exactly one lane, `Lane A`.

`[ ]` not started · `[~]` **started, outcome unknown** · `[x]` done, followed by
the commit hash carrying it (or `` `nocommit` `` plus a one-line reason — never
a blank). **`RV`/`RVJ` are the exception**: they produced review, not code, and
close on reviewer evidence instead of a hash — see below.

### Rule 1 — Read-write bookend at every phase boundary

- **Before starting ANY phase:** read `progress.md` **in full, first** —
  before dispatching an agent, opening a plan doc, reading source, or writing
  code. It is the phase's first tool call, not something you get to after
  "just checking one thing".
- **Before marking ANY phase complete:** update and save the tracker first —
  every task in that phase checked off **with its hash**, Current State
  pointing at the **next unchecked line** — which for a joining phase is its
  `RVJ`, sitting above that phase's first task — **and this phase's `RV` (and
  any `RVJ`) `[x]`**.
  **A phase is complete when the file says so**, not when you believe the work
  is done. No phase may be
  declared complete, and no next phase may begin, until that write is on disk.

### Rule 2 — Per-task updates, not per-phase

Around **each individual task**, in this order:

1. **Before the work starts:** mark the task `[~]` with a timestamp. Save.
2. Do the task.
3. On completion: mark it `[x]` with the commit hash.
4. Update the Current State block (this lane's `**Lane <id>:**` line, timestamp).
5. Save.
6. **Re-read the file** and take the next unstarted line from it — which, after
   a phase's last task, is that phase's `RV` (then any `RVJ`), not the next
   phase.

**You never run on memory across two tasks.** Re-orient from the file after
every single one. In a parallel wave (Rule 6) the same six steps run **per
member**: each member's `[~]` is written before *its* dispatch, each member's
`[x]` + hash is written as *it* lands — never one write for the wave.

Batching the updates — "I'll tick off the whole phase at the end", "I'll update
once this agent batch returns" — is the exact failure this
law exists to prevent. Step 1 is not optional bookkeeping: it is the only thing
that distinguishes "never started" from "died halfway" after a crash.

### Rule 3 — Twelve-task cap per phase

During **Stage 3 (plan expansion)**, no phase may contain **more than 12
tasks**. A phase whose expansion yields 13+ tasks **MUST be split into
sub-phases** (`4a`, `4b`, …), each ≤ 12 tasks, **before any implementation
begins**. Splitting after implementation starts does not satisfy this rule,
and neither does "12 tasks, some with sub-steps" — sub-steps that are
separately checkable are tasks. The split is part of the plan the user
approves at GATE 2, so it happens before the gate, not after it.

The `RV` and `RVJ` lines are **not** tasks and never count toward the 12.

A split phase is still **one designed unit**: after its last sibling passes, it
gets a **joint integration review** over the siblings' combined diff before the
run advances (see Reviewer fan-out).

### Rule 4 — Verify `[~]` tasks before doing anything else

On any **cold start** — new session, context compaction, resumed run, or your
own uncertainty about what just happened — read `progress.md`, `findings.md`
and `register.md`, then **reconcile every `[~]` task against the actual code**
(git state + the tests covering it) before taking any other action. Fully
applied → `[x]` with its hash. Partially applied → revert or deliberately
complete it, and if which one is correct isn't obvious from the plan, that is
an Ambiguity-guard stop. Nothing applied → back to `[ ]`.

**A `[~]` task is never assumed done because it looks done, and never assumed
untouched because you don't remember it.** Full procedure in
`references/run-state.md`.

A `[~]` **`RV`/`RVJ`** reconciles against `agent-output/`, not against the code:
the expected number of reviewer reports present and consolidated into
`findings.md` → `[x]` with its evidence; present but never consolidated →
consolidate them now; missing or short of the declared count → back to `[ ]` and
run the fan-out. Never resolve one by re-reading the diff yourself — that would
make you the reviewer, which is what the line records someone else being.

### Rule 5 — Hold pointers, not payloads

Context bloat is the other half of drift. **Every dispatched subagent returns
≤ ~10 structured lines** (task ID, status, commit, files, tests, ≤2 lines of
notes, and a `DETAIL:` path). Anything longer — diffs, full `/review` reports,
test logs — the subagent writes to `agent-output/<label>.md` and returns the
path. Put that instruction in every dispatch prompt.

The orchestrator reads a detail file **only when a decision depends on it**,
and then reads the file rather than a remembered version. Full reviewer reports
never enter orchestrator context wholesale; the consolidated list in
`findings.md` is what the run reasons over. Contract in
`references/run-state.md`.

### Rule 5b — Derive, don't restate

A brief, a plan or a comment states the **source** of a code fact — the symbol
it lives on, or the command that regenerates it — and never a count, a line
number, a signature or a file list. No method or field named as already
existing, no type, no "the four reachable states".

**A task's `Files:` block is the exception, at both ends** (Rule 6): writing it
into a plan — and into a task brief cut from one — is required, and receiving it
is not grounds for the refusal below. `references/parallel.md` says why no
derivation can stand in for those paths. Nothing else about a task's code
travels with a brief.

The reason is mechanical: a restated fact is correct at the moment it is written
and at no moment after. The orchestrator writes briefs from a tree that moves
under them, so a restated fact is wrong at a rate the run cannot absorb — and
because the agent receiving it treats the brief as authority, the error is only
caught when that agent happens to look. In testing every such error *was*
caught, by the agent, after it had already shaped the work.

- **Writing a brief:** name the symbol, not the file and line it currently sits
  at. Give the command that finds the call sites, not the number of them you
  counted.
- **Receiving a brief:** a brief that states a code fact is **refused** — send
  it back rather than reconciling it. You cannot tell a stale fact from a
  current one without deriving it, and if you are deriving it the brief's copy
  was worthless.
- **Writing a comment:** anchor to a symbol or delete the claim. A comment that
  asserts a re-derivable fact is a **claim finding** waiting to happen — see the
  closure rule in `references/fix-loop.md`.

This rule binds this skill's own prose. Where these documents once counted their
own templates, they name `templates/` instead: the count was true right up to
the commit that added a file to that directory, which is the same failure one
level down.

### Rule 6 — Dependency waves: parallel where the plan proves it is safe

Sequential-by-default is the fallback, not the design. At Stage 3 every task is
annotated with **`Depends on:`** (task IDs it consumes) and **`Files:`** (what
it creates or modifies), and every phase with the phases it depends on. From
those the orchestrator computes **waves** inside a phase and **lanes** across
phases, *before GATE 2*, and the user approves them as part of the plan:

- Two tasks share a wave **iff** neither depends on the other (transitively)
  **and** their `Files:` sets are disjoint. Otherwise the later one waits.
- Wave `k` dispatches only when every task of wave `k-1` is `[x]` **and merged**
  into the phase branch with the build gates green.
- A wave of one runs as today. A wave of two or more dispatches **all members at
  once**, each implementer in **its own git worktree and branch** cut from the
  phase branch head; members land independently and are merged back in task
  order once all of them have landed and the build gates are green. No member is
  reviewed before its merge.
- Phases with no dependency between them run as **concurrent lanes**, each an
  independent instance of the per-phase loop with its own Counters row.
- **Missing or vague annotations are not a licence to guess** — a task with no
  `Depends on:` / `Files:` goes back to its expansion agent. A merge conflict
  inside a wave means the annotations were wrong: abort the merge, re-open the
  conflicting task, redo it sequentially on the merged head.

Full procedure — annotation grammar, wave computation, worktree naming, the
merge step, lane close-out — in `references/parallel.md`.

### Brain-Agent mode (user-declared, recorded, never assumed)

The default pipeline asks the **user** every unknown. The user may instead
declare, in their own words, that questions go to a **Brain Agent** — a
dedicated subagent per question, given the full context, whose ruling closes
the register entry. That mode is **on only when the user's declaring message is
copied verbatim into `register.md`** under an "Operating mode" heading with its
date. No verbatim record → normal mode, no matter what you remember being told
(a previous run stalled for exactly this: a tracker claimed brain-agent gates,
the register had no such note, and the user had to be asked on resume).
Rules of the mode are in `references/parallel.md`.

## When to Use

- User wants a feature carried from idea all the way to a finished branch in
  one mostly-autonomous run.
- User says "run the whole pipeline", "take this end to end", "implement all
  phases", "don't stop between phases".

**When NOT to use:** a single bug fix (use `superb:bug-fix`), a one-off change, or when
the user wants to stay hands-on at every step (run the individual skills
directly).

## Two operating modes

- **Full mode** (default): starts at Stage 1 (interactive brainstorm).
- **Fix-mode** (set only by this skill's own fix loop, never by the user):
  **skips Stage 1 entirely**, treats a set of review findings as the spec, and
  writes no new top-level spec. The Ambiguity guard still applies at every
  depth. See `references/fix-loop.md`.

## Stage flow

```dot
digraph pipeline {
    "Stage 1: brainstorm question rounds (until register empty)" [shape=box];
    "Stage 1b: 2-agent pressure-test (gaps -> new questions)" [shape=box];
    "GATE 1: approve design (register must be empty)" [shape=diamond];
    "Stage 2: master plan (writing-plans)" [shape=box];
    "Stage 3: expand each phase (1 agent/phase, each runs writing-plans, annotates deps+files)" [shape=box];
    "Stage 3a: split any phase over 12 tasks; compute waves and lanes (Rule 6)" [shape=box];
    "GATE 2: approve expanded plan (register must be empty)" [shape=diamond];
    "Stage 4 IMPLEMENT: every task in the phase, waves of tasks (ambiguity -> ask)" [shape=box];
    "Stage 4 REVIEW: RV fan-out over the whole phase diff (all reviewers return first)" [shape=box];
    "Stage 4 DECIDE: consolidate, dedup, F-IDs, tiers" [shape=diamond];
    "Stage 4 FIX_PLAN: one scoped fix plan for this round's blocking findings" [shape=box];
    "Stage 4 FIX_IMPLEMENT: fix agents, one per file cluster" [shape=box];
    "Stage 4 RE_REVIEW: sized from the fix diff (C=<n>)" [shape=box];
    "CLOSE(review_gate): the gate that raised the findings goes [x]" [shape=diamond];
    "Stage 4 PASS: RV [x], close-out written and saved" [shape=box];
    "Stage 4b: joint integration review over a split's combined diff" [shape=box];
    "Stage 5: finishing-a-development-branch" [shape=doublecircle];

    "Stage 1: brainstorm question rounds (until register empty)" -> "Stage 1b: 2-agent pressure-test (gaps -> new questions)";
    "Stage 1b: 2-agent pressure-test (gaps -> new questions)" -> "Stage 1: brainstorm question rounds (until register empty)" [label="new unknowns"];
    "Stage 1b: 2-agent pressure-test (gaps -> new questions)" -> "GATE 1: approve design (register must be empty)" [label="register empty"];
    "GATE 1: approve design (register must be empty)" -> "Stage 1: brainstorm question rounds (until register empty)" [label="revise"];
    "GATE 1: approve design (register must be empty)" -> "Stage 2: master plan (writing-plans)" [label="approved"];
    "Stage 2: master plan (writing-plans)" -> "Stage 3: expand each phase (1 agent/phase, each runs writing-plans, annotates deps+files)";
    "Stage 3: expand each phase (1 agent/phase, each runs writing-plans, annotates deps+files)" -> "Stage 3a: split any phase over 12 tasks; compute waves and lanes (Rule 6)";
    "Stage 3a: split any phase over 12 tasks; compute waves and lanes (Rule 6)" -> "GATE 2: approve expanded plan (register must be empty)";
    "GATE 2: approve expanded plan (register must be empty)" -> "Stage 4 IMPLEMENT: every task in the phase, waves of tasks (ambiguity -> ask)" [label="approved"];
    "Stage 4 IMPLEMENT: every task in the phase, waves of tasks (ambiguity -> ask)" -> "Stage 4 REVIEW: RV fan-out over the whole phase diff (all reviewers return first)" [label="every task [x] + gates green"];
    "Stage 4 REVIEW: RV fan-out over the whole phase diff (all reviewers return first)" -> "Stage 4 DECIDE: consolidate, dedup, F-IDs, tiers";
    "Stage 4 DECIDE: consolidate, dedup, F-IDs, tiers" -> "CLOSE(review_gate): the gate that raised the findings goes [x]" [label="no blocking findings"];
    "Stage 4 DECIDE: consolidate, dedup, F-IDs, tiers" -> "Stage 4 FIX_PLAN: one scoped fix plan for this round's blocking findings" [label="blocking findings"];
    "Stage 4 FIX_PLAN: one scoped fix plan for this round's blocking findings" -> "Stage 4 FIX_IMPLEMENT: fix agents, one per file cluster";
    "Stage 4 FIX_IMPLEMENT: fix agents, one per file cluster" -> "Stage 4 RE_REVIEW: sized from the fix diff (C=<n>)";
    "Stage 4 RE_REVIEW: sized from the fix diff (C=<n>)" -> "Stage 4 FIX_PLAN: one scoped fix plan for this round's blocking findings" [label="blocking findings remain"];
    "Stage 4 RE_REVIEW: sized from the fix diff (C=<n>)" -> "CLOSE(review_gate): the gate that raised the findings goes [x]" [label="clean"];
    "CLOSE(review_gate): the gate that raised the findings goes [x]" -> "Stage 4 PASS: RV [x], close-out written and saved" [label="the gate was this phase's RV"];
    "CLOSE(review_gate): the gate that raised the findings goes [x]" -> "Stage 4 IMPLEMENT: every task in the phase, waves of tasks (ambiguity -> ask)" [label="the gate was a LEADING RVJ: the joining phase now STARTS, it does not PASS"];
    "CLOSE(review_gate): the gate that raised the findings goes [x]" -> "Stage 4 IMPLEMENT: every task in the phase, waves of tasks (ambiguity -> ask)" [label="the gate was a TRAILING RVJ: next phase"];
    "Stage 4 PASS: RV [x], close-out written and saved" -> "Stage 4b: joint integration review over a split's combined diff" [label="last sibling of a split"];
    "Stage 4b: joint integration review over a split's combined diff" -> "Stage 4 FIX_PLAN: one scoped fix plan for this round's blocking findings" [label="blocking findings"];
    "Stage 4b: joint integration review over a split's combined diff" -> "CLOSE(review_gate): the gate that raised the findings goes [x]" [label="clean"];
    "Stage 4 PASS: RV [x], close-out written and saved" -> "Stage 4 IMPLEMENT: every task in the phase, waves of tasks (ambiguity -> ask)" [label="next phase"];
    "Stage 4 PASS: RV [x], close-out written and saved" -> "Stage 5: finishing-a-development-branch" [label="all phases done"];
}
```

### Stage 1 — Brainstorm (interactive question rounds + agent pressure-test)

The stage order is fixed: **question rounds → pressure-test → synthesis →
GATE 1.** Never merge these into one message, never present a design before
the questions are answered, never run the pressure-test after the gate.

0. Read `references/run-state.md`. Create the run directory at
   `<PROJECT_DIR>/docs/superpowers/runs/YYYY-MM-DD-<topic>/`, copy in the
   templates, seed `progress.md` with Stages 1–5 as phases (all `[ ]`, Current
   State = Stage 1), state the full directory path in your first message to the
   user, then read the tracker back. `kit.md` is the exception: it cannot be
   filled in before the plan names the gates, so GATE 2 writes it and this step
   does not. **If the directory already exists, stop and ask** — resume, fresh
   run, or abort — showing the user its Current State.
1. Invoke `superpowers:brainstorming` for the interactive Q&A.
2. Run **as many question rounds as it takes** until you can state every
   requirement with zero open Assumptions Register entries. Each new answer
   that reveals new unknowns spawns another round. More rounds = correct.
   - **The repo's commit and verification conventions go in the first round** —
     the ticket/issue key required in a commit subject (and this run's value
     for it), any coverage floor on changed lines, and any pre-push gate. A
     **written** repo rule is the one kind of unknown `register.md`'s *Decided
     without asking* table lets you settle alone, but only once you have
     **found** it, and inference is not finding. **The seeded key entry asks two
     things and its halves go to different tables:** whether this repo demands a
     key at all is answered by the written rule, so that half belongs in *Decided
     without asking* with the rule cited the moment you find it — and in *Open*
     only while you cannot; which key this run uses is answered by nobody but the
     user, so that half stays *Open* and blocks GATE 1 until they say it. Every
     task in the run commits,
     so a wrong answer here is wrong in every commit. Seed them as register
     entries, cite the rule that answers each, and record the answers in
     `kit.md`'s *Project specifics* at GATE 2. A run that discovers its commit
     convention at Stage 5 cannot apply it without rewriting history.
3. **Intercept** before brainstorming auto-transitions to writing-plans — this
   skill owns that transition.
4. Dispatch **≥2 agents in parallel** to independently pressure-test / expand
   the agreed design (red-team, surface gaps, propose extensions).
5. Every gap the pressure-test surfaces becomes either a design change the
   user explicitly confirms or a **new register question** — never a
   self-filled default. If new entries opened, return to step 2.
6. Synthesize into one design.
7. **GATE 1: user approves the synthesized design.** Register must be empty.
   Write the spec to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
   (a spec MAY be committed as permanent documentation, but nothing does it
   for you, so treat it as local until you commit it — Stage 5 is what
   carries its decisions into something durable).

### Stage 2 — Master plan
Invoke `superpowers:writing-plans` on the approved spec → one phased master
plan. **Every phase heading names the phases it depends on** (`deps: none` /
`deps: A1, B2`) — that is what Stage 3a turns into lanes. Any decision the spec
doesn't cover → register entry → ask before GATE 2.

### Stage 3 — Per-phase expansion
For each phase, dispatch a subagent that **MUST invoke
`superpowers:writing-plans`** to expand that phase into a detailed, internally
consistent sub-plan (its own doc). It does NOT hand-roll the expansion. Run
these in parallel. **Every task in the sub-plan carries a `**Depends on:**`
line (task IDs, or `none`) beside its `**Files:**` block** — the expansion
prompt says so, and a returned doc missing either on any task goes straight
back to its agent. Expansion agents report ambiguities back instead of
resolving them; those become register questions.

Each expansion also ends its phase with the phase's **`RV` line**, so review is
in the plan the user approves rather than something the run is trusted to
remember. Splits and lane joins additionally get an **`RVJ`** (Stage 3a, once
the split and the lanes are known).

**Enforce the 12-task cap here.** When the expansions return, count the tasks
in each phase. Any phase over 12 is split into sub-phases of ≤ 12 tasks
(`4a`, `4b`, …) **now** — before GATE 2, before any implementation. Then
**compute the waves of every phase and the lanes across phases** (Rule 6,
`references/parallel.md`), write them into each sub-plan as a `## Waves`
table, and check the result: no two tasks in one wave share a file, no task
precedes one of its deps. The split, waved, laned plan is what the user
approves.

**GATE 2: user approves the full expanded plan.** `register.md` must have no
open entries. Last routine gate — **and the last gate is a stop, not the end of
the work** (see *Gates are stops; stages are work*). On approval, rewrite
`progress.md`'s phase lists from the approved plan (every phase with its
`deps:` **and its `· lane:`** — allocated here, once, and never recomputed —
every task with its `W<n>` and `deps`, **every phase closed by its own
`RV` line**, all `[ ]`, sub-phases kept adjacent so a split's siblings are
visibly one unit) and set Current State to the first wave of every lane's first
phase before Stage 4 starts.

Write the `RV` lines **now**, at the same time as the task lines — plus an
`RVJ` under the last sibling of every Rule 3 split and at every point where two
lanes join. A review line added later is a review line that can be forgotten;
one written at GATE 2 is part of the plan the user approved.

### Compacting at GATE 2

Stage 4 is the long stage — one orchestrator turn per dispatch, an implementer
for every task of every phase, then that phase's review fan-out and any fix
rounds it opens. Your whole context is re-sent on each of them. Stage 1's question rounds
are the worst of it: Rule 5 keeps agent *output* out of context behind a
`DETAIL:` pointer, but a conversation with the user cannot be pointer-ised. It
is simply there, re-sent every turn until the run ends.

GATE 2 is also the safest point in the run to lose it. The design is in the
spec, the plan in its files, the register empty by law, and the user has just
approved both — almost nothing of value exists only in the conversation. That
stops being true the moment Stage 4 starts: implementation generates knowledge
(why an approach was rejected, which invariant is load-bearing and why) that is
not on disk yet. Cheapest and safest are the same point, and this is it.
**Never offer this at GATE 1** — a compact costs a summarisation pass and voids
the prompt cache, so the next turn re-reads everything. That pays back across
the whole of Stage 4, not across the handful of turns GATE 1 has left.

**Flush first, in this order. Then offer.**

1. `register.md` has no open entries and `findings.md` no open blocking IDs.
2. `progress.md`'s Current State carries one `**Lane <id>:**` line per active
   lane, every phase heading carries its `· deps:` **and its `· lane:`**, every
   task line carries its wave and its deps, every phase carries its `RV` line,
   and every split and lane join carries its `RVJ`.
3. **`kit.md` is written** — the suite, coverage and build-gate commands the
   approved plan names, the baseline discipline, the mutation harness, the
   worktree rule, and the repo conventions Stage 1's question rounds asked
   for. It is
   **written once, here, from the approved plan**, because every dispatch after
   this point cites it by path instead of deriving the apparatus again; a run in
   which every task re-derives one harness is the cost this file exists to
   delete. Commands only, never their output (Rule 5b).
4. **Every decision made in conversation and never written down gets written
   now** — into the spec if it changed the design, into a phase's plan if it
   changed that phase's approach, into the register's Closed table verbatim if
   it was an answer. This is the step, not a formality: skip it and "we
   discussed it" quietly becomes "nobody knows".
5. If step 4 changed the design or a phase's approach, the plan in front of the
   user is wrong. Correct it, re-present the gate, and let the offer ride with
   the **corrected** gate message — never over an unapproved change.

Then **offer** it, in the GATE 2 message. You cannot compact yourself — there
is no tool for it — so it is the user's action and the user's call: say what is
now on disk, what a compact would discard, and that Stage 4 re-reads the files
anyway (Rules 1 and 4), so it resumes from the same state either way. They may
want the design conversation for something else.

### Stage 4 — Autonomous per-phase loop

For each phase — in dependency order, independent phases concurrently as lanes
— see `references/fix-loop.md`. **A phase is a transaction:** it is the unit of
execution and the unit of acceptance, and the run stays inside it until it
passes.

```
IMPLEMENT ─► REVIEW ─► DECIDE ─┬─ no blocking findings ─────► CLOSE(review_gate)
                               │                                        ▲
                               └─ blocking findings                     │
                                    ▼                                   │
                                  FIX_PLAN ─► FIX_IMPLEMENT ─► RE_REVIEW┤
                                    ▲                                   │
                                    └──────── blocking findings remain ─┘

CLOSE(review_gate) is the clean terminal of BOTH paths — a first round that
raised nothing and a re-review that came back clean close the same way. What it
unlocks depends on which gate closed:

    CLOSE(RV)           ─► phase PASS ─► NEXT_PHASE
    CLOSE(trailing RVJ) ─► NEXT_PHASE
    CLOSE(leading RVJ)  ─► IMPLEMENT the joining phase, which still owes
                           IMPLEMENT ─► RV ─► CLOSE(RV) ─► PASS of its own
```

**0. Read the tracker in full** — first action of the phase, before any dispatch
— and reconcile any `[~]` line (Rule 4). It, not your memory, names the phase,
its state, and its next open line.

**IMPLEMENT** — `references/implement.md`.
Dispatch every task in the phase, wave by wave per the approved wave table.
Mark each `[~]` before its dispatch and `[x]` with its commit hash as it lands
(Rule 2). Merge each wave in task order and run the build gates.
```
COMPLETING AN IMPLEMENTATION TASK DISPATCHES NO REVIEWER.
```
The only transition here is task → next task. An implementer fixing its own
compile error, failing test or obvious mistake is implementation, not the fix
loop — and so is a red build gate after a wave merge: it means the
implementation is not finished, so it is repaired here and re-gated here. **No
remediation round opens before `RV`.** No finding, no F-ID, no fix plan, no
Counters row; the formal states begin only where REVIEW leaves off.
*Exit:* every task line in the phase `[x]` with a hash (or a justified
`nocommit`), every wave merged, build gates green.

**REVIEW** — the phase's `RV` line.
Mark `RV` `[~]` **and save first** — it is a tracker line and Rule 2 governs it.
`N` = the phase's task count → dispatch the slice reviewers in parallel:
**`ceil(N/5)`, whatever the wave count was.** Waves schedule implementation;
they do not size review, and a slice may split tasks that ran in one wave.
Each owns an exact **commit range** from the tracker's
hashes, each runs the repo `/review` skill, each returns a report file even when
it finds nothing. Add an integration reviewer **only at a declared integration
boundary** (see *Reviewer fan-out*). Confirm the slices cover every commit on
the phase branch, including any you wrote inline yourself. Run the test suite —
failing tests are bug findings.
```
REVIEW MAY NOT BEGIN WHILE ANY TASK IN THIS PHASE IS UNCHECKED.
ALL REVIEWERS MUST RETURN BEFORE ANY FIX IS DISPATCHED.
```
A reviewer discovers problems; it never starts a fix. Do not dispatch a fixer
because the first report came back while others are still out.
*Exit:* every dispatched reviewer has returned.

**DECIDE.**
Consolidate + dedup every report into `findings.md`, **assigning each new
finding a stable `F-NNN` ID**. **Three tiers only** — Critical / Major (=
`/review` "Warning") / Minor; ties within them resolve upward; a rediscovered
finding keeps its old ID; **an incoming `Important` is re-tagged** to Major or
Minor by the predicate in `references/fix-loop.md` and never carried as a tier. Close `RV` `[x]` with those F-IDs — or `no findings` — its
`agent-output/` paths and its coverage file.
- **No Critical/Major/bug** → `PASS`. Minor findings defer to the Stage 5
  hand-off; they are not blocking and not discarded.
- **Any Critical/Major/bug** → `FIX_PLAN`. **The phase does not advance.**

**FIX_PLAN** — `references/fix-loop.md`, and required.
Write the phase's fix plan for this round to
`agent-output/p<phase>-fixplan-r<round>.md` from `templates/fix-plan.md`, and
name it on the round. Findings → fix plan → fix implementation, in that order.
No fix is dispatched before its plan is on disk.

**FIX_IMPLEMENT.**
Execute the fix plan with the **minimum reasonable number of fix agents** — one
per independent file cluster the plan names, related findings batched together.
Fix agents run the tests covering their change. They do not review their own
fixes as a substitute for `RE_REVIEW`.

**RE_REVIEW.**
Reopen the **`review_gate`** — the `RV` or `RVJ` that raised these findings, and
never a different one — to `[~]` and append this round **under that gate's own
line**. An `RVJ`'s round belongs to the `RVJ`; filing it under a joining phase's
`RV` spends that phase's review budget on a join it never covered. Size it from the **fix diff** — one
slice per file cluster, recorded as `C=<n>` — never from the finding count. The
re-review reads: whether the blocking findings were actually resolved, the fix
diff, regressions the fixes introduced, interactions between fixes, and whether
the phase now satisfies its plan. It is not a rerun of the original per-slice
structure.
- Clean → `PASS`.
- Blocking findings remain → back to `FIX_PLAN` for the next round, subject to
  the convergence rule (an ID still open after a fix run that targeted it, or a
  repeated open-ID set, stops the run with a user question — **before** the
  caps).

**PASS.**
Only with all of this true and **written and saved**: every task `[x]` with its
hash; required tests and build gates green; the phase's `RV` `[x]` carrying
every round's F-IDs or `no findings`, its `agent-output/` paths and coverage;
every fix plan the rounds name present in `agent-output/`; no open blocking F-ID
scoped to this phase; Current State pointing at the **next unchecked line**.
The `RV` condition is listed first because it is the only one an unreviewed
phase fails — the others all pass vacuously when REVIEW never ran.

For the **last sibling of a Rule 3 split**, the next unchecked line is the
split's **`RVJ`**, not the next phase: the joint review over the siblings'
combined diff runs and closes `RVJ` `[x]`, its blocking findings going through
the same fix loop, before the run advances. The last sibling's own `RV` never
substitutes for it.

**NEXT_PHASE.**
```
PASS IS THE ONLY EDGE INTO THE NEXT PHASE.

Implementation complete is not phase complete.
All task lines [x] is not phase complete.
An empty ledger is not phase complete.
```
If the fix loop cannot converge, **stop and ask the user**. A cap firing or the
convergence rule firing never licenses the next phase — those are escape
hatches out of the run, not around the gate.

Stage 4 is autonomous about **execution**, not about **requirements**: the
Ambiguity guard (below) interrupts the run whenever the plan doesn't decide
something. "No user stops" means no routine check-ins — it has never meant
"guess instead of asking".

### The Continuation Law (no stopping without a question)

```
AFTER GATE 2, EVERY STOP MUST CARRY A GUARD-RAIL QUESTION.
NO QUESTION IN YOUR MESSAGE = YOU ARE NOT ALLOWED TO BE STOPPING.
```

**Ending your turn is stopping.** A phase summary that yields back to the user
is a stop, whether or not it asks anything. So the test is mechanical: before
ending any turn between GATE 2 and Stage 5's hand-off, look at the message you
are about to send. Does it end with a question that a **named guard rail**
authorizes (Ambiguity, convergence, a cap, an existing run dir, an
unreconcilable `[~]`, unexplained commits)? If not, **do not end the turn** —
the next action is already written in the tracker; take it.

A phase boundary is executed **inside one turn**, as one motion — and the
boundary begins at the phase's `RV`, not after it:

1. The phase's last task landed, so the next line is its **`RV`**: mark it
   `[~]`, dispatch the fan-out, consolidate, close it `[x]` with its evidence.
   (If this is the last sibling of a split, its **`RVJ`** follows the same way.)
2. Only then close out the phase (Rule 1 write: all `[x]` + hashes, `RV` `[x]`,
   Current State advanced, saved).
3. Re-read the tracker.
4. Dispatch the next phase's first task.

Narrate progress **inline** — one or two lines between tool calls ("Phase 2
closed, 12/12 tasks, starting Phase 3") is fine and useful. What is forbidden
is making that narration the end of your message. Progress reports are
milestones passed at speed, not stations to wait at.

**The Stage 5 hand-off is the next designed stop after GATE 2.** Between them,
either you are executing, or your message ends in a guard-rail question and
names which guard rail fired. There is no third state.

**Waiting on a dispatched agent is executing, not stopping.** A wait is a tool
call; the turn has not ended and no guard rail is required. "I have nothing to
do until the implementer returns" is never the end of a turn — it is the reason
to wait. Which wait, and whether skipping it parks the run, is the platform
question below.

### Who wakes you after a dispatch (read before your first dispatch)

Harnesses differ on one point that decides whether ending a turn is free or
fatal, and the skill cannot tell from inside which one it is running on. Find
out before you dispatch anything.

| Harness family | What happens when a dispatched agent finishes | Ending your turn with children outstanding |
| --- | --- | --- |
| **Re-invoking** (e.g. Claude Code) | The completion starts a new turn for you | Costs nothing — you will be woken |
| **Mailbox** (e.g. Codex `spawn_agent` / `wait_agent`) | Its answer is placed in a mailbox that **only a new turn drains**, and completion **cannot itself start one** | **Parks the run** until the user types something |

On a mailbox harness the rule is mechanical, not motivational:

> Whenever you have dispatched agents outstanding and no local work left, your
> next action is a **bounded wait**, not the end of your turn. Repeat the wait
> until the mailbox delivers or you have a guard-rail question to ask.

Bound each wait in long stretches — on Codex, `wait_agent` with `timeout_ms`
between 300000 and 600000. The wait is an event subscription, so a long stretch
wakes just as fast as a short one; stacking short polls buys nothing and costs
a tool call and a context rebill each. A stretch that times out with no
activity is a cue to reconcile against git, not to shorten the next stretch.

Read your harness's own reference for the exact tool names — on Codex that is
`superpowers:using-superpowers`'s `references/codex-tools.md` — and **trust
your actual tool list over any table, including this one.** If you cannot
establish which family you are on, treat it as a mailbox harness: waiting on a
re-invoking harness is harmless, while ending your turn on a mailbox harness is
the "stops after every task" failure, and it is the user who pays for it, once
per task, by having to type *continue*.

### Stage 5 — Finish
Read `progress.md` first and confirm every phase is `[x]` with a hash **and
that every phase's `RV` — and every `RVJ` — is `[x]`**. Do not take the tick on
trust: this is the run's one independent pass over lines whose author had the
motive to skip them, so **stat the `reports` paths and count them against the
`<s> + <i>` on each line, per round, and check each coverage file ends
`COVERED: <n>/<n>`.** A round that carries no reviewer evidence at all does
not fail that count — the round forms that owe none are the exception named in
`references/fix-loop.md`'s *Invariants*, and each is read against its own
closure fields. A line that fails what it owes is an unreviewed phase wearing a
green tick — treat it as `[ ]`. Any `[ ]` or `[~]` is unfinished work,
not a bookkeeping lapse — go finish it (a `[~]` goes through Rule 4
reconciliation first). An open `RV` means that phase was implemented and never
reviewed: go run its fan-out before anything else, however many phases back it
sits. Confirm `findings.md` has no open blocking IDs and `register.md` no open
entries.

**Then run the `RV`-grammar linter over this run's own directory**, before the
hand-off: from a checkout of the superb plugin's own repository,
`./tools/check-plugin.sh --run <run-directory>`. It reads the same tracker you
have just checked by hand, and it catches the kinds of thing a hand check slides
over — a count that was never added up, a report or coverage file named but
never written, a coverage table that handed two reviewers the same range.
The linter lives in that repository and does **not** ship with the plugin, so a
run in any other project may have no checkout to run it from; that is why the
result goes in the hand-off either way rather than being a gate.

**What a `FAIL` means for the pass you have just done.** Reporting it is not
the whole of it: a **`FAIL` on any check the by-hand pass also owes is that
pass failing**, so treat that line as `[ ]` and go run its fan-out, exactly as
if you had caught it by hand. The linter's checks are a superset of the count
you did above, so without that rule one defect reopens `RV` when a human finds
it and ships as a hand-off line when the linter finds it. Every other `FAIL`
is reported in the hand-off, which the sentence above already requires.

Invoke `superpowers:finishing-a-development-branch`. Because the run directory
is local-only, **the hand-off is the run's only durable
output besides the commits**, and MUST include:

- the **deferred Minor-findings table** from `findings.md` (ID, finding, file,
  phase) so the user decides their disposition — fix now, ticket, or accept;
- **every phase whose `RV` closed as `WAIVED by user`**, with the quoted
  instruction — the run's only durable record that code shipped unreviewed;
- a **summary of the approved design and the decisions the register closed**,
  written so it still makes sense to someone who never had the local spec;
- the **`RV`-grammar linter's result over this run's own directory** — its
  `check-plugin: PASS`/`FAIL` output quoted, and every `FAIL` line with it. When
  no checkout of the plugin's own repository was available to run it from, say
  precisely that instead: **the linter was unavailable, so the tracker's review
  lines went unchecked**. Do not drop the item — an absent line reads as a
  check that passed, which is the one thing it must never read as.

Anything that matters and appears only in a run-directory file is one lost
machine away from gone. Put it in the hand-off.

## Reviewer fan-out (the `ceil(N/5) + integration` rule)

| Tasks in phase (N) | Slice reviewers | Integration reviewer | Total |
|--------------------|-----------------|----------------------|-------|
| 1–5                | 1               | 0 (one slice sees all) | 1   |
| 6–10               | 2               | 0, or 1 at a declared boundary | 2–3 |
| 11–12              | 3               | 0, or 1 at a declared boundary | 3–4 |

Rule 3 caps a phase at 12 tasks, so `N > 12` cannot occur. If you are computing
a fan-out for N of 13 or more, the phase was never split — go back and split it.

Each slice reviewer sees ONLY its slice's diff so findings map back to
specific tasks; the integration reviewer sees the whole phase diff and hunts
only cross-slice and cross-phase issues no single slice can see.

**Reviewers are dispatched at the standard capable tier or above**, and a
phase whose diff is architecture-sensitive takes the strongest available — the
fan-out is the largest dispatch class in a run, so the tier is chosen here and
not defaulted (`references/implement.md`, *Choosing the model*). A slice
reviewer reads a range against a plan; that is not cheap-tier work, and a
reviewer that misses a cross-slice contract mismatch costs a whole fix round.

**The integration reviewer is spent on a boundary, not on a slice count.** Three
reviewers over an 8-task phase whose slices share no contract read the same code
twice; that third reviewer's whole value is in what crosses between slices. So it
is dispatched where something crosses — a Rule 3 split's siblings joining, two
lanes joining, or a contract introduced in one slice and consumed in another that
no single slice's range covers — and the round names it (`· boundary: <what>`).
Where nothing crosses, the round declares `· no integration boundary`: the
absence is a decision on the record, not a gap, because an omission and a
judgement are indistinguishable to every later reader.

**Where something does cross, it is not optional.** The two mandatory cases keep
their own line and their own mandate: a split's `RVJ` and a lane join's `RVJ` are
`0 slice + 1 integration` always, because there the boundary *is* the unit nobody
else saw. And slice coverage does not change — every commit on the phase branch
still falls inside some slice's range, and that is still a check you run.

**Slices are commit ranges, not vibes.** Take each slice's boundaries from the
hashes recorded against its tasks in the tracker. Tasks that touch the same
files make a "contiguous ~5 tasks" slice ambiguous; `<first>^..<last>` does not.
A phase that ran waves (Rule 6) is sliced no differently: review slices are cut
**after the phase's implementation has landed**, into approximately balanced
contiguous ranges covering the whole phase diff. A slice **may** split work that
executed in one implementation wave — implementation independence and review
partitioning are different concerns.

**The slices must cover the phase's whole diff, and that is a check you run.**
Task hashes are where boundaries come from; they are not the definition of the
scope. Before dispatching, list the phase branch's commits —
`git log --oneline <phase-base>..<phase-head>` — and confirm every one falls
inside some slice's range. A commit no slice covers is code that reaches the
hand-off unreviewed.

**Commits you authored yourself are covered like every other commit.** Glue, a
merge fixup, "a few lines" written inline instead of dispatched — these have no
task line and therefore no hash in the tracker, so slicing by task hashes alone
leaves them out **by construction**. That makes orchestrator-authored code the
*least*-reviewed code on the branch: an implementer's work is at least read by a
reviewer, while yours was read by nobody. Extend a slice to swallow it. Being
the author is not a review, and knowing it is correct is what every author
believes.

### Re-review fan-out (different math)

`ceil(N/5)` is defined over **tasks**. Fix-mode returns produce fix commits,
not tasks, so a re-review is sized from the **fix diff**: **one slice reviewer
per file cluster**, plus an integration reviewer above one cluster **only at a
declared boundary** named on the round, and `· no integration boundary`
otherwise — the same conditional rule the phase fan-out takes, and
`references/fix-loop.md`'s *Re-review fan-out* table is its authority.
`M` is still recorded on the round, and `M=0` still licenses a round with no
reviewers in it — but `M` does not size the fan-out, because six comment
corrections in one file are one small diff and three reviewers over it
duplicate each other. **The cluster count is recorded on the round as `C=<n>`
and `s` must equal it** — what declaring it establishes, and what it does not,
is stated with the rule in `references/fix-loop.md`. Slice boundaries are the
fix commits' ranges, **no two slices carry the same range**, and **the assigned
ranges must union to cover every fix commit a reviewer can own** — a clean
round from reviewers who never looked at a fix closes nothing.

**What `M` is, and which closure routes come out of it, is stated once** — in
`references/fix-loop.md`, fix loop step 3 — and deliberately not restated here.
This is the section a reader consults to decide whether a round runs, which is
exactly why it must not carry a second gloss of a closed list: a gloss that loses
one route mandates a round over an empty diff, or excuses a commit that needed an
owner. Table in `references/fix-loop.md`.

### Joint integration review after a split (Rule 3)

Splitting a 20-task phase into `4a`/`4b` gives each sibling its own integration
reviewer — but that reviewer only ever sees one sibling. **Nobody sees the unit
the phase was designed as.** So: when the **last** sibling of a split passes its
own review, run **one joint integration reviewer** over the combined diff of all
siblings, before the run advances past the split.

- Scope: the union of every sibling's commits, reviewed as one phase.
- It hunts exactly what per-sibling reviewers structurally cannot see —
  contracts introduced in `4a` and consumed in `4b`, `4b` regressing `4a`,
  duplicated or conflicting work across the split.
- It is the split's **`RVJ`** line, and closes with the same evidence an `RV`
  carries. Its findings get F-IDs like any others; blocking ones run the fix
  loop under the **`RVJ`'s own Counters row** — not the siblings' shared row,
  which they may already have spent — and their rounds are appended under the
  **`RVJ`'s own line**, because the gate that raised a finding is the gate whose
  evidence has to answer for it. Then `CLOSE(RVJ)`, and only then advancing.
- The same review, and the same line, is owed wherever **two lanes join**
  (`references/parallel.md`).
- The split is an artifact of the 12-task cap, never a reason to review less.

## Gates are stops; stages are work

A **gate** is a place the run stops to ask the user. A **stage** is work the run
performs. The user can wave the run past a stop. **Waiving a stop does not
delete the work behind it.**

This matters most in the turn after GATE 2, because that approval is worded as
permission to keep going and Stage 4 is where the run stops asking. "Approve and
continue", "don't stop between phases", "run it to the end", "take it all the
way", "I'm busy" — each removes **check-ins**. None removes the review fan-out,
the test run, the ledger, or the tracker writes. A user who waives being asked
has not waived being protected.

Only an instruction that **names the work** removes the work — "skip the code
review", never "continue". And when the user does say it, it is a decision
recorded like every other: verbatim in `register.md`, and on each affected
phase's `RV` line, which closes `[x]` carrying the waiver **in place of**
reviewer evidence:

```markdown
- [x] RV — review fan-out · WAIVED by user: "skip the code review on this one"
```

That is the only way an `RV` closes without reviewer output, and Stage 5's
hand-off **MUST list every phase closed this way**, so what shipped unreviewed
is visible in the run's one durable artifact rather than resting on your memory
of a permission.

**Nothing substitutes for the fan-out.** Implementer self-reports and their own
mutation tests, a green suite, Stage 1b's design pressure-test, an
implementer's own self-check, your own read of the diff — each is blind
to something a fresh reviewer sees, and the rationalization table says why for
each. The defects this catches are the author-blind ones: **a change correct in
its own lines that activates broken code elsewhere**, a contract produced in one
task and misused in another, a regression into an earlier phase.

## Guard rails (autonomy escape hatches)

After GATE 2, the run stops only for a tripped guard rail. Full semantics in
`references/fix-loop.md`:
- **Ambiguity guard** (uncapped): any decision not answered by the approved
  spec, the expanded plan, or a written repo rule → **stop, ask the user,
  wait for the answer, resume.** Ambiguity stops never count toward the caps.
- **Convergence rule** (uncapped): an **F-ID still open** after a fix-mode run
  that targeted it, or an open-ID set that repeats an earlier iteration's →
  **stop, show the attempts, ask the user.** The comparison is over ID sets in
  `findings.md`, never a judgment about whether two prose descriptions mean the
  same thing. Never re-dispatch fix-mode on a spec that already failed
  unchanged; the cap is a backstop for slow progress, not the designed
  surfacing point.
- **Recursion depth cap = 2** on fix-mode runs.
- **Fix-loop iteration cap = 5** per phase.
- At either cap → **stop and surface to the user** with the unresolved findings.

**Both counters live in `findings.md`, not in your context** — read the Counters
row before every cap check, and write the increment before dispatching. A cap
compared against a remembered number is not a cap: one compaction mid-fix-loop
resets it to zero and the loop runs unbounded.

## Rationalization table

Every one of these was observed verbatim in testing. They all mean: STOP. ASK.

| Excuse | Reality |
|--------|---------|
| "The user said keep questions to a minimum" | Busy changes the question format, not the count of unknowns resolved. Batch the round; ask everything. |
| "Reply 'approved'/'go' to accept all defaults" | Bulk replies close zero register entries. Each assumption needs its own answer. |
| "I'll list my assumptions so the user can veto by exception" | An assumption the user didn't explicitly confirm is still an assumption. Ask it as a question instead. |
| "Codebase precedent is the strongest non-user disambiguator" | Precedent tells you what exists, not what the user wants. Precedent may inform your suggested option — inside a question. |
| "I'll put the line numbers in the brief so the agent finds it faster" | A line number is correct when you write it and at no moment after. Name the symbol, or the command that finds it. |
| "The brief says 12 call sites; close enough to act on" | The last brief that stated a call-site count stated the wrong one, and the agent reading it found that out. A stated code fact is refused, not reconciled. |
| "I'll pick the cheapest-to-reverse option and log it" | A logged assumption is still an assumption. The decision log is not a consent mechanism. |
| "Stopping would violate the skill's autonomy contract" | The Ambiguity guard IS part of the contract. Guessing violates it; asking honors it. |
| "The user said don't stop / is unavailable; the review fan-out will catch it" | Reviewers check code against the plan; they cannot read the user's mind. Wait for the user. |
| "Industry standard / it's obvious" | The user's product is not the industry average. Obvious to you ≠ chosen by them. |
| "One more assumption won't matter, I need to show progress today" | Progress built on a wrong guess is negative progress. Ask first. |
| "I know what phase I'm in, re-reading `progress.md` is wasted tokens" | Knowing is the drift. The file is authoritative precisely when you feel certain. Read it. |
| "The skill folder has templates, I'll just write there" | `templates/` is read-only and shared by every project. Run state goes in the run directory. |
| "I'll drop the tracker in the repo root / cwd, close enough" | The path is exact: `docs/superpowers/runs/YYYY-MM-DD-<topic>/`. A tracker nobody can find again is drift with extra steps. |
| "A run directory already exists — it's obviously mine, I'll resume it" | Obviously-mine is an assumption about someone else's unfinished work. Show its Current State and ask: resume, fresh, or abort. |
| "A stale run directory is in the way; I'll just overwrite it" | That destroys an unfinished run's only record. It is a question, never a cleanup. |
| "I'll mark the task done when I know the outcome — `[~]` first is a wasted write" | `[~]` is the only thing that tells the next agent "died halfway" instead of "never started". Write it before the work. |
| "The task is obviously finished, I don't need the hash" | A hash is checkable; "obviously finished" is not. Blank hash = unverifiable = the drift you're preventing. |
| "This `[~]` looks done, I'll tick it and move on" | Rule 4: verify against git and the tests. Looks-done is exactly how half-applied work gets built on. |
| "The register/ledger is in my context, writing it to a file is duplication" | Your context is one compaction from empty. A rule with no file behind it is unenforceable. |
| "These two findings are basically the same one from last round" | That's the interpretive call the ID system exists to remove. Look up the F-ID. |
| "The comment was wrong, I corrected it — finding closed" | A corrected assertion is still unexecuted, and nothing keeps it true as the code under it changes. A claim finding closes by deleting the claim or pinning it with a test. Nothing else. |
| "I'll re-review the fix to the docblock to be safe" | Do. A deletion is a repository change, so its commit is owed a fix plan and a focused re-review like any other; a pin opens one over the test it commits, never over the claim; a rewrite is not a closure. Only a **withdrawal** and a **user-ruled false positive** leave nothing to review. |
| "I'll read the full review report so I don't miss anything" | Full reports in orchestrator context are the bloat that causes drift. Consolidate to `findings.md`; read details on demand. |
| "4a and 4b each passed review, the phase is covered" | Each reviewer saw half a designed unit. Run the joint integration review over the combined diff. |
| "This is iteration 2, I'm well under the cap of 5" | Unless you read that from `findings.md`, you are guessing after a compaction that may have eaten iterations 1–4. Read the row. |
| "I'll record the iteration once I see how the fix went" | Then a crash mid-fix loses it and the cap resets. Increment in the file before dispatching. |
| "The fix was small, one reviewer over the whole thing is fine" | One reviewer per file cluster in the fix diff, and the ranges must cover **every fix commit the run produced** — a claim **deletion**'s is in the union like any other, because deleting a claim changes the repository, and so is a claim **pin**'s. "Small" is a judgement about clusters, not a licence to skip coverage. |
| "The re-review came back clean, the findings are closed" | Only if its ranges actually covered the fix diffs. Union the ranges and check before closing anything. |
| "I'll note the design decision in the spec doc and move on" | The run directory is never committed, and nothing commits the spec for you. If it matters, it goes in the Stage 5 hand-off too. |
| "`resume` obviously means the most recent directory" | Recency is a guess about someone's unfinished work. More than one candidate → show each Current State and ask. |
| "It's just `status`, I'll quickly fix that failing test while I'm here" | `status` is read-only; a fix is a run. Report it and let the user invoke `resume`. |
| "The phase is done — I'll summarize and let the user take it from here" | A summary that ends your turn is a stop with no question. Narrate inline and start the next phase in the same motion. |
| "Shall I continue with Phase 3?" | The plan the user approved at GATE 2 already answers that. Asking again is a routine check-in — the thing 'no user stops' forbids. |
| "So much just changed, it feels right to pause and show the user" | Feels-right is not a guard rail. If nothing is ambiguous, the tracker names your next action — take it. |
| "I did a lot this turn; a natural break point" | Turns are not phases. The only designed stops after GATE 2 are tripped guard rails and the Stage 5 hand-off. |
| "I'll stop here so the user can review the phase" | Phase review is the fan-out's job, done. The user's review points are the gates and Stage 5 — they chose them at approval time. |
| "I'll tick off the whole phase at the end — same result, fewer writes" | Per-task is the rule. A crash, a compaction, or a wrong turn mid-phase leaves the file lying about state. |
| "The subagent reported which tasks it finished, that's my source of truth" | An agent report is memory, not the ledger. Write it to the tracker, then read the file back. |
| "Parallel implementers conflict, so I'll run the wave one at a time" | They conflict in one worktree. Rule 6 gives each member its own worktree and disjoint files — the plan the user approved says these run together. Serialising a wave is ignoring the approved plan. |
| "Two `[~]` lines at once breaks Rule 2" | Rule 2 is per-task writes, not one-task-at-a-time. Wave members each get their own `[~]` before their own dispatch. |
| "The user is in a hurry, I'll parallelise these tasks that look independent" | Looks-independent is an assumption. Waves come from the `Depends on:`/`Files:` annotations the user approved at GATE 2, never from a glance at task names. |
| "No `Depends on:` line — I'll infer the deps from the task text" | Inference is the guess Rule 6 forbids. Send the doc back to the expansion agent. |
| "The wave merge conflicted; I'll resolve the hunks myself" | A conflict proves the `Files:` sets overlapped. Abort, re-open the task, redo it sequentially on the merged head. |
| "The user told me earlier to use brain agents instead of asking" | Only the verbatim record in `register.md` turns that mode on. Not there → ask the user. |
| "The register is empty and the plan is approved — there is nothing to flush, just compact" | Empty tables are two checks of three. The third is the decision the user made out loud that no file records. Walk the conversation first. |
| "The user asked for the compact now; the flush can follow" | Then it follows an empty context. Write first, compact second — that order is the only thing that makes the cheap move safe. |
| "Compaction helps at GATE 1 too, same argument" | The argument is a whole stage of re-sent context. GATE 1 has a handful of turns left, and a compact costs a summarisation pass plus the prompt cache. |
| "13 tasks is basically 12, splitting is bureaucratic" | The cap is a number, not a vibe. 13 tasks → split before implementation. |
| "The user said 'approve and continue' — review was ceremony they waived" | Gates are stops; stages are work. They waived being asked, not being protected. Only "skip the code review" waives review, recorded verbatim. |
| "Each lane self-verified — several ran mutation tests and killed every mutant" | An implementer grading its own diff is the exact failure independent review prevents. Self-verification is not the fan-out. |
| "Stage 1b already put three agents on this design" | That pressure-tested a document before the code existed. It cannot review lines nobody had written. |
| "`findings.md` has no open blocking IDs, so the phase passes" | An empty ledger is what an unreviewed phase looks like too. The `RV` line says whether review happened; the ledger only says what it found. |
| "Tests are green and every implementer returned SUCCESS — that is the check" | Green tests are an input to step 2, named inside it. Agent reports are memory. Neither is a reviewer. |
| "I wrote those few lines inline, I know they're fine" | You are the author. Orchestrator commits have no task hash, so no slice covers them unless you extend one — they are the least-reviewed code on the branch. |
| "The last phase closed out this way and nothing broke" | Precedent inside one run is the defect propagating, not evidence it is safe. Check the `RV` lines and backfill every open one. |
| "I'll run the reviewers at the end, over the whole branch at once" | Per-phase is the rule: findings are cheapest while the phase is fresh and unmerged, and four merged lanes make attribution guesswork. |
| "The lane line says Phase 4 T1, and the file is the truth" | It is — and the same file has an open `RV` line above the one it names, which is the earlier unchecked line. The Law is unchanged: read the phase lists, take the *first* unfinished line, and correct a Current State that skipped it. This licenses nothing beyond an open `RV`/`RVJ`. |
| "I'll split the oversized phase once I see how it goes" | Splitting after implementation starts does not satisfy Rule 3. Split before GATE 2. |

## Red flags — STOP and ask the user

- You are writing the words "I assumed", "industry standard", "sensible
  default", "reasonable default", or "I'll proceed with X unless you say
  otherwise".
- You are about to present a gate while any register entry is open.
- You are merging question rounds and the gate into one message "to save the
  user time".
- You are mid-Stage 4 choosing between two implementations that differ in
  user-visible behavior.
- You are telling yourself the skill forbids interrupting the user.

**All of these mean: convert the unknown into a question, send it, and wait.**

## Red flags — STOP and re-read the run state

- You are about to start a phase and your first tool call is not reading
  `progress.md`.
- You are starting work on a task you have not yet marked `[~]`.
- You are dispatching two implementers into the **same** worktree, or one
  implementer for a task whose wave-mates are still `[ ]`.
- You are dispatching wave `k` while a wave `k-1` member is not `[x]`, or the
  wave merge has not run the build gates.
- You are closing a register entry with a Brain-Agent ruling and the register
  has no verbatim "Operating mode" declaration from the user.
- You are past a `[~]` task without having reconciled it against the code.
- You are checking a task `[x]` and have no hash to put next to it.
- You are about to hold a full diff or review report in your own context
  instead of a `DETAIL:` path.
- You are putting a line number, a file list, a signature or a count into a
  brief, a plan or a comment instead of naming the symbol, or the command that
  derives it.
- You are deciding whether two findings are "the same" instead of comparing
  F-IDs.
- You are about to state an iteration number or recursion depth you did not
  just read out of `findings.md`.
- You are sizing a re-review fan-out off task count or off the targeted F-ID
  count instead of off the fix diff's file clusters.
- You are closing **any** finding whose fix changed the repository without
  having checked that a re-review range actually covered that fix — a claim
  finding closed by **deletion** included, since removing the sentence is a
  commit a reviewer can read. (A **pin** opens a round too, but over the test it
  commits — the claim is closed by the pin itself. Only a **withdrawal** and a
  **user-ruled false positive** leave no range to check.)
- You are between GATE 2 and Stage 5, about to end your turn, and the message
  you are sending contains no guard-rail question. **Keep going instead.**
- Your message ends with a phase summary, "let me know if…", or "shall I
  continue" — a question the approved plan already answers.
- You are naming the current phase or the next task **from recollection**
  rather than quoting the file.
- You finished a task and moved straight to the next one without writing.
- You are about to say a phase is done, and the file still shows open tasks.
- You are about to tick a phase complete while its **`RV` (or a split's
  `RVJ`) is `[ ]` or `[~]`** — that phase was implemented and never reviewed.
- You are closing an `RV`/`RVJ` round with fewer `reports` files than the
  reviewers that round declares, or a coverage file that does not end
  `COVERED: <n>/<n>` — on a round that owes those fields. The forms that owe
  none are the exception in `references/fix-loop.md`'s *Invariants*.
- You are writing a lane line that names the **next phase** while this phase's
  `RV` is still open — or that names a phase assigned to a different lane.
- You are writing the Stage 5 hand-off and it carries nothing about the
  `RV`-grammar linter — neither its output nor the statement that no checkout
  was at hand to run it from.
- You are at Stage 5 and any phase's `RV` is not `[x]`, or `findings.md` is
  thin against the run's size. Check the `RV` lines phase by phase rather than
  the ledger as a whole: one Minor from one reviewed phase makes a ledger look
  alive while six other phases went unreviewed.
- You are dispatching slice reviewers without having listed the phase branch's
  commits to confirm every one lands inside a slice.
- You are reconstructing "where were we" from the conversation, a plan doc, or
  a subagent's report instead of from the tracker.
- You are treating the file as a summary you keep in sync, rather than the
  record you take orders from.
- The path you are about to write to is inside a skill directory, or is not
  under `<PROJECT_DIR>/docs/superpowers/runs/<this run>/`.
- You are about to offer, or agree to, a compact without having walked the
  conversation for decisions no file records.

**All of these mean: read the run state in full now, and let it — not your
memory — decide what happens next.**

## Composed skills (never reimplemented)
`superpowers:brainstorming`, `superpowers:writing-plans`,
`superpowers:finishing-a-development-branch`, and the repo `/review` skill
(the deep branch-audit skill in this repo, not a generic code review).

`superpowers:subagent-driven-development` is deliberately **not** composed here.
It has no implementation-only mode — an implementer returning `DONE` dispatches
a reviewer for that task, and a task completes only at zero open findings at any
severity through an uncapped fix/re-review loop — and it is phase-unaware. Stage
4's IMPLEMENT state is `references/implement.md` instead.

## Common mistakes
- **Assuming instead of asking** — the only failure mode. See the Iron Law.
- **Running on memory between tasks** — the second failure mode. The tracker
  is read after every task, not consulted when you feel lost.
- **Writing run state into the skill directory** — it lives in the project's run
  directory. `templates/` is read-only.
- **Silently resuming or overwriting an existing run directory** — that's a
  user question, both ways.
- **Skipping the `[~]` mark** — without it a dead session cannot tell
  "not started" from "half applied".
- **Checking a task `[x]` with no commit hash** — the hash is what makes resume,
  slice ranges, and fix-diff verification mechanical instead of interpretive.
- **Keeping the register or findings ledger in context only** — a compaction
  erases them, and "a finding stays open until closed" becomes unenforceable.
- **Minting a new F-ID for a rediscovered finding** — it keeps its original ID,
  or the convergence rule can never fire.
- **Closing a claim finding by rewriting the sentence** — the rewrite is the
  next round's finding. Delete the claim, or pin it with a test; a rewrite
  closes nothing, and the fix loop it starts has no fixed point.
- **Pulling full review reports or diffs into orchestrator context** — hold the
  `DETAIL:` path; read it only when a decision needs it.
- **Advancing past a split without the joint integration review** — per-sibling
  reviewers each saw half the designed unit.
- **Keeping the iteration/depth counters in context** — a compaction resets them
  to zero and both caps silently stop capping. They live in `findings.md`.
- **Sizing a re-review off task count or off finding count** — fix diffs aren't
  task-shaped and findings aren't diff surface; one reviewer per file cluster,
  with ranges covering **every fix commit the run produced** — a claim
  **deletion**'s included, since it changes the repository, and a claim
  **pin**'s, which commits a test.
- **Compacting before the flush** — the Run State Law is only true once the
  files actually hold everything; GATE 2's flush is what makes it true.
- **Assuming a local spec is a durable record** — the run directory is never
  committed, and a spec is only durable once someone deliberately commits it;
  the Stage 5 hand-off is what survives either way.
- **Ending the turn on a phase summary** — the most common silent failure.
  A stop with no guard-rail question is an unauthorized stop even when it asks
  nothing; close out, re-read, and dispatch the next phase in the same turn.
- **Batching progress writes to the end of a phase** — Rule 2 is per-task.
- **Entering or completing a phase without the read-write bookend** — the read
  is the phase's first action; the write precedes the completion claim.
- **Leaving a 13+ task phase unsplit** — Rule 3 is enforced at Stage 3, before
  GATE 2 and before any implementation.
- **Serialising a wave** — the approved plan said those tasks run together, in
  separate worktrees. One-at-a-time is the fallback for a wave of one, not a
  safety margin you add.
- **Parallelising by eye** — waves come from annotations approved at GATE 2,
  not from tasks that "look independent" mid-Stage 4.
- **Treating a remembered brain-agent instruction as the operating mode** — the
  verbatim record in `register.md` is the switch; nothing else is.
- **Reimplementing a stage** instead of invoking its skill. Always delegate.
- **Letting brainstorming auto-jump to writing-plans** — intercept after the
  design is agreed so the 2-agent pressure-test and GATE 1 happen.
- **Reordering Stage 1** — pressure-test runs before GATE 1, and its gaps
  become user questions, not self-filled defaults.
- **Advancing or finishing with an open `RV`/`RVJ`** — the phase was
  implemented and never reviewed. Every other completion check passes vacuously
  in that state, because they all read a ledger an unrun review leaves empty.
- **Skipping the per-phase `writing-plans` expansion** — Stage 3 agents must
  call the skill, not summarize the phase themselves.
- **Re-interviewing the user in fix-mode** — fix-mode skips Stage 1; the
  findings are the spec. (The Ambiguity guard still applies.)
- **Looping forever** — honor both caps; surface to the user at the cap.
- **Burning iterations on a non-converging finding** — the convergence rule
  stops at the first evidenced wasted iteration; don't ride it to the cap.
- **Trusting a clean re-review that never covered the fix** — a round whose
  ranges never looked at the fix diff closes nothing; failing to be
  rediscovered is not a closure. The ledger's route for a behavioural finding
  is fix-diff-touched **plus** a covering re-review; a claim finding takes a
  different route (deleted, or pinned with a test — both of which commit
  something a round then owns), so the lesson is what a clean round cannot buy
  you, not
  that this is the only way to close.
- **Advancing with a red test suite** — failing tests are bug findings even
  when no reviewer reported them.
- **Blocking on Minor findings** — only Critical/Major/bug gate advancement;
  Minors are deferred to the Stage 5 hand-off, never discarded.