| name | fable-plan |
| description | Author an execution-grade implementation plan for a feature or fix, saved as a dated spec under docs/specs/, detailed enough that Opus agents can execute it end-to-end without Fable in the loop. Invoke when the user starts with /fable-plan, asks for a "fable plan", or wants a task planned for later Opus execution rather than built now. |
| argument-hint | <task to plan> [--dir <output-dir>] |
Fable plan — execution-grade spec authoring
You are the planner, not the builder. The task statement is everything that
followed the invocation:
$ARGUMENTS Your output is a spec folder another model executes verbatim,
possibly weeks from now, with zero access to your reasoning — so every
judgment call you make while researching must end up written down. The division
of labor: the hard part is thinking (architecture, sequencing, ambiguity
resolution); execution should be left mostly mechanical.
Precedent plans (read one before your first plan; match their density):
docs/specs/2026-07-02-timezone-history-migration/ (single-agent),
docs/specs/2026-07-05-event-clustering/ (orchestrated). The format contract
lives in docs/specs/2026-07-01-fable-plan-queue/README.md § "Plan format".
Step 1 — Scope and prior art
- Output location:
docs/specs/$(date +%Y-%m-%d)-<slug>/ (run date; never
hardcode). If the invocation names a different directory, use that instead.
- Check
docs/specs/INDEX.md and docs/specs/2026-07-01-fable-plan-queue/README.md
for prior specs or queue items covering this task — a plan often supersedes an
older analysis doc; say so in the README and link it.
- Read the relevant
CLAUDE.md files (src/finance/CLAUDE.md,
frontend/CLAUDE.md) before planning work in those trees.
Step 2 — Research until nothing is ambiguous
Read the actual code — every module the change touches, every consumer of the
data it alters. Depth here is the whole point; skimming produces plans that
Opus has to re-derive, which defeats the skill.
- Anchors from the live tree only. Every
file:line reference in the plan
must come from a Read/Grep you ran this session — never from memory or an
older spec (specs go stale; the tree is truth).
- Build the consumer map. For any data shape, key, or contract the plan
changes, enumerate everything that reads or writes it (side stores, pointer
fields, caches, journal files, fixtures, e2e specs). Missed consumers are the
#1 way executed plans corrupt data.
- Find the traps. Identify the plausible-but-wrong implementation an
executor would naturally reach for, and write down why it's wrong (the
timezone plan's "bucketing trap" section is the model).
- Resolve every fork. Each design decision gets analyzed and locked as
L1, L2, … with a one-paragraph rationale. Technical forks you resolve
yourself using the codebase's own conventions. Use AskUserQuestion only for
genuinely product-owned forks (scope, user-visible behavior, data-loss
tradeoffs) — never for anything the code can answer.
Step 3 — Write the deliverables
README.md — the why and the what
Header: title, **Status:** Not Implemented (Fable-authored; build-ready),
**Date:**, links to parent spec / queue item if any. Then:
- Context — what exists today (with anchors), what's broken or missing,
why now. Concrete failure narratives beat abstract motivation: show the
corruption/bug/gap with real field values.
- Why this is subtle — the traps section. Only if there are traps; don't
manufacture drama.
- Locked decisions —
L1…Ln, each with rationale. Include an explicit
deferred / do-not-build list as its own locked decision so scope can't
creep during execution.
- Contracts — API shapes, schemas, key formats, algorithm constants. If an
algorithm matters, spell it out verbatim (named constants, formulas) and lock
it — "reasonable clustering" is not a spec.
- Verification — how a human confirms the finished work end-to-end.
IMPLEMENTATION_PLAN.md — the how
Open with the standing instructions: execute phases in order, gates must pass
before advancing, decisions in README are final ("do not re-derive them"), all
Python via uv run.
- Phase 0 — re-validate anchors. A checkbox list of every load-bearing
anchor the plan rests on, one line each with what should be found there.
Gate: every box checked against the live tree. Include the drift protocol:
if an anchor moved, update the plan file in place and note the drift in the
commit body. (Plans are executed later; this phase is what makes staleness
survivable.)
- Phases 1…n, each with:
- Concrete deliverables: file paths to create/modify, function signatures,
dataclass fields, SQL statements, endpoint shapes. Include short code
snippets only where prose would be ambiguous (a hash recipe, a
ConditionExpression, a regex) — not for code Opus can write from a clear
sentence.
- Enumerated tests — name the test module and list the cases, including
the edge cases your research surfaced (boundaries, DST, collisions,
resume-after-crash). "Add tests" is not a plan line.
- Repo rules restated inline where they bite (dual-backend edit discipline,
queries.* factories, brand voice for user-facing strings) — don't assume
the executor read every CLAUDE.md section.
- A gate: literal commands with expected outcome
(
uv run pytest tests/unit/test_x.py -v green; ruff + pyright clean).
- Final phase: docs updates (guides, ARCHITECTURE.md, CHANGELOG if
user-visible,
docs/specs/INDEX.md status flip) and make verify green.
- Sequencing rule: pure logic before I/O before CLI/UI — early phases should be
exhaustively unit-testable without infrastructure.
- If anything at plan-time is unknowable until build time (e.g. the next free
migration number), say exactly how Phase 0 resolves it rather than guessing.
GOAL.md — the runnable prompt
One bare paragraph, no fences, no commentary — the exact text pasted to a
fresh agent. Name the spec directory, the read order (README → plan →
relevant CLAUDE.md), the phase sequence with one clause per phase, and the
standing rules: decisions are final, gates before advancing, uv run only,
commit per phase via /commit, finish with make verify green. Model:
docs/specs/2026-07-02-timezone-history-migration/GOAL.md.
ORCHESTRATE.md — only when it pays
Write it only if the work splits into ~3+ packets with disjoint file
ownership that can genuinely run in parallel. Model:
docs/specs/2026-07-05-event-clustering/ORCHESTRATE.md. Must include: worktree
isolation (mandatory — this repo runs multiple agents against one shared
index), a work-packet table with exclusive file ownership, orchestrator-run
gates (subagent claims are never trusted), ≤2 SendMessage feedback rounds per
packet before the orchestrator fixes residuals itself, self-contained briefs
(packet ID, read list, locked decisions by name, traps, deliverable contract,
no commits by subagents), and stop clauses. Single-agent work: skip this file;
GOAL.md is enough.
Step 4 — Register and stop
- Add a row to the top table of
docs/specs/INDEX.md: status Not Implemented,
summary column carrying the load-bearing locked decisions, second column
noting "build-ready Fable plan" and the file inventory.
- If the task came off the fable-plan-queue, annotate that queue entry
(
← planned <date>; see <folder>/).
- Do not commit the plan:
docs/specs/ is local-only via
.git/info/exclude. (If the user pointed output at a tracked location,
offer /commit instead.)
- Do not start implementing. The deliverable is the plan. End by telling
the user the folder path, the locked-decision count, and the one-line launch
instruction (paste
GOAL.md to an Opus agent, or run ORCHESTRATE.md if
written).
Quality bar — self-check before finishing
Reject your own draft if any of these fail:
- Could Opus start Phase 1 without asking a single question? Every "it
depends" must already be an
Ln.
- Is every anchor from this session's reads, and is each one in the Phase 0
checklist?
- Does each phase end in a gate an agent can mechanically evaluate?
- Are the tests enumerated case-by-case, edge cases included?
- Is there an explicit do-not-build list?
- Would a plausible-but-wrong implementation slip through? If you can name
one, the traps section must kill it.
