Implementation plan
Plans are repo artifacts, not chat messages. They are also the durable session state - a fresh session must be able to pick one up and continue.
Where plans live
Follow the repo's existing convention: docs/superpowers/plans/ where established, else docs/plans/. Naming matches the repo's pattern: YYYY-MM-DD-<slug>-plan.md, with phase/ticket codes when in use (sp2b, l7, 2a-backend). Split large work into paired plans (backend/frontend, a/b) like the existing corpus.
Recon before writing (never plan blind)
- Read the approved PRD/spec section, ticket, or explicit user request that defines the change; cite requirement IDs where they exist. Stop only when the source scope is ambiguous, contradictory, or requires authority the user has not provided.
- Reuse inventory: search for existing models, services, components, and utilities. If most of the need already exists, the plan extends or refactors it. Roughly 80% is a recon heuristic, not a numeric gate.
- Read the target module's current patterns (naming, error handling, tests) and the repo
constraints in AGENTS.md and/or CLAUDE.md.
- Note which domain skills apply (ledger, temporal, migrations, spring-api, igaming-ui) and cite the specific invariants this work must satisfy.
Plan structure
- Context - requirement IDs, system-of-record/ownership boundaries, negative constraints (what NOT to touch: CI config, curated copy, other teams' modules).
- Decisions - for one-way choices, a 5-line inline ADR (options, choice, why); follow the repo's
docs/adr/ convention when one exists.
- Slices - vertical, independently shippable, ≤~1 day each. Per slice: files touched, reuse notes, migration (if any), tests to write (before the code where practical), verification command + expected output, checkbox.
- Flow map (only for stateful/risky flows: money movement, sagas, auth) - path table covering happy/failure/timeout/recovery, each row mapped to a test-case ID; plus a cleanup inventory (resource / allocated when / orphan risk / cleanup mechanism).
- Cleanup list - legacy code and files this work must delete, plus separately authorized database cleanup. Greenfield repos: no unnecessary compatibility layers, deprecated columns, or half-migrations.
Bar
Done when any slice could be executed by a fresh session without questions, and every slice says how it will be verified. As short as completeness allows - no essay sections. Execution proceeds slice by slice via build.
Resume mode ("status?", "what is pending?")
Answer from the plan document, never from recollection. Read the most recently dated plan that still has unchecked boxes; when several are active, report each briefly rather than guessing which one is meant. Reconcile its checkboxes against reality - uncommitted diff, branch state, last verify output - before reporting, and report any contradiction as a discrepancy; correct the document when work resumes, not in answer to a status question. Close with done vs pending slices and the single next action.
1---2name: plan3description: Use when a feature, refactor, or fix needs an implementation plan before coding - turning an approved spec, ticket, or explicit user request into an executable, verifiable plan document. Also when picking work back up after a context reset or a break: "status?", "what is pending?", "where were we".4---56# Implementation plan78Plans are repo artifacts, not chat messages. They are also the durable session state - a fresh session must be able to pick one up and continue.910## Where plans live11Follow the repo's existing convention: `docs/superpowers/plans/` where established, else `docs/plans/`. Naming matches the repo's pattern: `YYYY-MM-DD-<slug>-plan.md`, with phase/ticket codes when in use (`sp2b`, `l7`, `2a-backend`). Split large work into paired plans (backend/frontend, a/b) like the existing corpus.1213## Recon before writing (never plan blind)141. Read the approved PRD/spec section, ticket, or explicit user request that defines the change; cite requirement IDs where they exist. Stop only when the source scope is ambiguous, contradictory, or requires authority the user has not provided.152. Reuse inventory: search for existing models, services, components, and utilities. If most of the need already exists, the plan extends or refactors it. Roughly 80% is a recon heuristic, not a numeric gate.163. Read the target module's current patterns (naming, error handling, tests) and the repo17 constraints in AGENTS.md and/or CLAUDE.md.184. Note which domain skills apply (ledger, temporal, migrations, spring-api, igaming-ui) and cite the specific invariants this work must satisfy.1920## Plan structure21- **Context** - requirement IDs, system-of-record/ownership boundaries, negative constraints (what NOT to touch: CI config, curated copy, other teams' modules).22- **Decisions** - for one-way choices, a 5-line inline ADR (options, choice, why); follow the repo's `docs/adr/` convention when one exists.23- **Slices** - vertical, independently shippable, ≤~1 day each. Per slice: files touched, reuse notes, migration (if any), tests to write (before the code where practical), verification command + expected output, checkbox.24- **Flow map** (only for stateful/risky flows: money movement, sagas, auth) - path table covering happy/failure/timeout/recovery, each row mapped to a test-case ID; plus a cleanup inventory (resource / allocated when / orphan risk / cleanup mechanism).25- **Cleanup list** - legacy code and files this work must delete, plus separately authorized database cleanup. Greenfield repos: no unnecessary compatibility layers, deprecated columns, or half-migrations.2627## Bar28Done when any slice could be executed by a fresh session without questions, and every slice says how it will be verified. As short as completeness allows - no essay sections. Execution proceeds slice by slice via `build`.2930## Resume mode ("status?", "what is pending?")31Answer from the plan document, never from recollection. Read the most recently dated plan that still has unchecked boxes; when several are active, report each briefly rather than guessing which one is meant. Reconcile its checkboxes against reality - uncommitted diff, branch state, last verify output - before reporting, and report any contradiction as a discrepancy; correct the document when work resumes, not in answer to a status question. Close with done vs pending slices and the single next action.
OmexIT