planning

Planning

Build a plan by collaborative interrogation, then stress-test it adversarially, before coding. The deliverable is a plan file, or the tickets that plan splits into when the work is too big for one pass. Never code.

• IS: building a plan from intent through one-question-at-a-time interrogation (Create), and strengthening an existing plan by scoring six dimensions to 5/5 with claim verification (Review). Both write to the plan file. When the work exceeds one plan, both exit through the split in references/splitting.md, which publishes vertical-slice tickets.
• IS NOT: implementing or generating code, authoring a PR (use pr-creator), reviewing a code diff (use pr-reviewer), or writing an architecture brief (use codebase-architecture).

Pipeline position: planning (create then review) -> implementation -> pr-reviewer -> pr-creator -> pr-babysitter.

Mode dispatch

Auto-detect; ask only if genuinely ambiguous:

• No plan file in scope, or verbs like "create a plan", "plan this", "grill me", "think this through" -> Create mode.
• Existing plan in scope (a path, pasted plan, or recent file in the active agent's native plan directory), or verbs like "review my plan", "stress test", "is this ready", "get this to 5/5", "verify this claim", "fact-check this plan" -> Review mode.
• No plan in scope but the user asks to verify or fact-check a standalone claim -> answer directly with local evidence; create no plan artifact.
• If the input is code or a diff rather than a plan, stop and route to pr-reviewer.

Create hands off to Review; a plan is not ready for implementation until Review passes.

Decision principles

Use these to cut scope, sequence work, and challenge the plan. Turn each into a plan edit; never cite slogans.

1. KISS: fewest moving parts that satisfy the current requirement. Delete layers, modes, config, or coordination that do not change the first shippable outcome.
2. As simple as possible, no simpler: never cut correctness, permissions, observability, rollback, migration safety, or required edge states. A smaller plan that drops a current requirement is too small.
3. YAGNI: defer extension points, future providers, generic frameworks, and speculative settings until a named current requirement needs them.
4. Proven practice: when the ecosystem or repo has a proven pattern for this exact problem, use it and name the precedent. Invent a local pattern only when a concrete constraint makes the standard one fail.
5. Easier to change: make the next likely requirement local. Name what file, module, table, or API boundary changes later, and what stays untouched.
6. Tracer bullet: prove the approach with one minimum viable vertical slice across the real boundary before building horizontal layers.
7. DRY: deduplicate knowledge, invariants, protocols, and business rules, not coincidental shape.
8. Duplication over wrong abstraction: keep similar code duplicated when the shared abstraction would hide different business rules, lifecycles, owners, or failure modes.
9. Ladder of least code: for each piece of new code the plan calls for, take the first rung that holds: reuse what is already in the codebase, then stdlib, then a native platform feature, then an already-installed dependency, then the minimum new code. A plan step that adds a dependency, or new code a higher rung plausibly covers, must say why the higher rungs fail.