milestone-brief

/milestone-brief — Fable escalation (RB → RR)

Read ${CLAUDE_PLUGIN_ROOT}/skills/shared/tracking-rules.md first and obey it. Phase header: # Review brief RB<NN> → ## Draft / ## Gate / ## Ingest. Chapter markers: mark a chapter at each phase transition (session start implicit). Fable is token-billed pay-per-use: spawning it requires explicit user approval, every time, with no standing authorization — and only ever through this protocol. The brief artifact comes first either way; it is what makes the review reproducible and its findings ingestible.

Creating a brief

1. Determine the next RB number (max across cairn/reviews/ and its archive, +1). Create cairn/reviews/RB<NN>-<slug>.md from ${CLAUDE_PLUGIN_ROOT}/skills/shared/templates/brief.md. It must be fully self-contained (assume zero conversation context): background, exact files/lines to examine, numbered specific questions (never "thoughts?"), constraints with D-entry links, and the required output path cairn/reviews/RR<NN>-<slug>.md.

2. Set the milestone blocked (work-log line: "blocked on RB"). Commit (docs-only, main): brief RB<NN>: <topic>.

3. Approval gate (AskUserQuestion): present the brief's scope, a rough size estimate (files/lines Fable must read), and a reminder that Fable is token-billed. Acceptance chips (tracking-rules): show the drafted RB's question and scope text verbatim above the gate, never only a description. Options:

   • Spawn Fable subagent (recommended) — on approval, launch an Agent with model: "fable" ([F]-tagged description) whose entire prompt is: read cairn/reviews/RB<NN>-<slug>.md and follow its instructions exactly, writing findings to the RR path it specifies. When it returns, run ingestion (below) immediately in this session.
   • I'll run it manually — this is a handoff, so the prompt goes in a fenced block, never a blockquote or inline backticks (tracking-rules "Copy-run commands"): a blockquote renders no copy button and the user has to retype the path. Tell them to open a fresh Fable session in the repo root, and emit the prompt as its own copyable block:

     Read cairn/reviews/RB<NN>-<slug>.md and follow its instructions exactly.
     

     Then stop the turn; ingestion happens at the next session start.
   • Cancel — unblock the milestone; note the question as unresolved in the work-log.

4. Never spawn Fable without this gate, and never proceed past the blocking question while the RB is open.

Ingesting an RR

Runs immediately after a spawned review returns, or automatically at session start (any skill) when a manual RR appears:

1. Read the RR. Record its answers as dated entries in the milestone's Decisions section; promote cross-cutting ones to cairn/DECISIONS.md.
2. If a recommendation contradicts a standing D-entry: supersede, don't ignore — quote the prior rationale to the user and only proceed by appending a superseding D-entry. Never silently override the record, and never silently discard Fable's advice.
3. Apply or schedule recommendations as tasks (or candidate rows for out-of-scope ones), each triaged: apply / consider / reject-with-reason (logged). Binding criteria travel verbatim: when the RR carries a ## Binding criteria section, the milestone it constrains sets its header's Driving RR: slot to RR<NN> and ingests each criterion verbatim into its ## Acceptance criteria as a numbered acceptance criterion carrying its trace tag — - [ ] AC-N (BCn): <verbatim> — and gives that criterion its own ## Coverage line: coverage-complete counts every AC checkbox positionally, so a bare, unnumbered BC checkbox reds that check (M107). This runs through the /milestone-implement step-6 amendment gate when the AC block already exists. After ingesting, re-check the plan-owned body with cairn_budget; if the added criteria push it over, compress the single heaviest plan-owned section in one pass (tracking-rules), never a nibble-and-recount loop. Any departure is a row in the "Deviations from RR" table at the end of that AC section, shown verbatim at this ingestion's preview, never slipped — IP3 applied to review findings. cairn_validate's binding criteria check string-compares the AC block against the RR (whitespace-normalized): a softened criterion is a red check, not a reading. Copy the RR's numeric projections beside the criteria with their stated tolerances; an unstated tolerance is strict — any shortfall forces the accept-shortfall option at the merge gate.
4. Relocate the RB/RR pair to cairn/reviews/archive/ with plain mv then git add, never git mv — an in-session-generated or hand-dropped RR is untracked, and git mv fails on an untracked file; milestone status back to in-progress; durable-record preview (tracking-rules): show the Decisions entries, D-entries, and candidate rows the ingestion wrote verbatim in chat before the commit; commit (docs-only): ingest RR<NN>.
5. Routing chip (AskUserQuestion), composed from where the RR left the milestone — e.g. Resume implementation → /milestone-implement <id> (recommended) / Stop here. Acceptance chips (tracking-rules): the RR's conclusions/verdict section is shown verbatim above the chip.

Robustness:

• Pasted RR content: if the user pastes review output into chat instead of the file, normalize it — write the RR file from the paste verbatim, then ingest as usual. Never reject usable review output on formal grounds.
• Non-responsive RR: if the RR fails to answer the brief's questions, mark it unresolved and draft a fresh RB (new number) rather than re-ingesting a bad artifact.