Planning

Planning

Build a plan by collaborative interrogation, then stress-test it adversarially, before coding. The deliverable is always a plan file, 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.
• 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 define-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.

Conflict rule: current requirements win first. Then as simple as possible, no simpler bounds KISS and YAGNI; duplication over wrong abstraction bounds DRY; tracer bullet beats horizontal foundation work unless the project cannot run without that foundation.

Reference files

| File | Mode | Read when | |------|------|-----------| | references/interrogation-protocol.md | Create | Create Step 2: question decision tree, recommended-answer format, fuzzy-term patterns, anti-rationalization table | | references/doc-grounding.md | Create | Create Step 1, when design docs, RFCs, ADRs, or library/API docs are relevant: find them, extract the decisions they encode, grill the rationale | | references/html-question-form.md | Create | Create Step 2, optional: batched HTML question form for large or greenfield specs instead of one-at-a-time chat | | references/plan-quality-rubric.md | Review | Review Step 2 triage: 1-5 scoring criteria per dimension | | references/questioning-framework.md | Review | Review Step 3: question templates and pushback patterns per dimension | | references/dialogue-examples.md | Review | Before the Review dialogue: tone calibration and all four moves in action | | references/claim-verification.md | Review | When a claim is checkable against local code, docs, or specs, or the user asks to verify one |

Create mode

Create progress:
- [ ] Step 1: Understand intent (read the request, scan code and docs, state findings)
- [ ] Step 2: Interrogate (one question at a time; end with the "radically simpler?" challenge)
- [ ] Step 3: Synthesize (write the plan file, format matched to scope)
- [ ] Step 4: Validate (check the plan against the original request, report the path)
- [ ] Step 5: Hand off to Review mode

Step 1: Understand intent

Before asking, scan code and docs:

• Identify modules, files, and patterns related to the request; note conventions, abstractions, boundaries, and prior art.
• Read relevant design docs, RFCs, ADRs, READMEs, referenced library/API docs, and any spec the user points to. Load references/doc-grounding.md to find docs and extract their decisions and rationale.

State findings in 2-3 sentences before the first question.

Step 2: Interrogate

Load references/interrogation-protocol.md. Ask ONE question at a time. Every question carries a recommended answer grounded in Step 1: name the file, function, approach.

• If code or docs can answer it, answer it yourself; never spend a user question on it.
• Each answer shapes the next. Walk the decision tree: resolve intent and scope before approach, approach before risks.
• Flag fuzzy terms ("handle auth", "make it fast"): propose a sharp version and ask if it is right.
• Surface tensions with existing code: "The codebase does X. You're proposing Y. Which wins?"
• Grill the core decisions: when docs reveal a decision, interrogate why it was made and whether the rationale still holds. Never re-ask what docs answer; pressure-test the reasoning.

Budget: 5-10 questions, then synthesize.

Mandatory scope challenge (before synthesizing): ask "What can we cut without dropping a current requirement?" Carry a recommended cut list: removed extension points, setup collapsed into the first vertical slice, abstractions kept only when they protect a shared invariant/owner/lifecycle, and safety gates preserved where "simpler" would drop correctness. Challenge the sum of the plan, not each piece.

Batch mode (optional): for large or greenfield specs with many independent questions, generate one local HTML form. Load references/html-question-form.md for the template and batch-vs-sequential table. Default to one-at-a-time when answers should shape later questions.

Escape hatch: if the user says "just write the plan", push back once via the anti-rationalization table, then respect their call and skip to Step 3.

Step 3: Synthesize

Write the plan file to the active agent's native plan directory when one exists; otherwise to the user-specified path or the repo-local plan location set by project instructions. Match format to scope.

Lightweight (single file, clear approach): # Title, ## Context (one paragraph), ## Approach.

Standard (multiple files, decisions made): # Title, ## Context (problem, what prompted it, intended outcome), ## Approach (recommended only), ## Key decisions (brief rationale), ## Files to modify (grouped by purpose), ## Out of scope (related-looking things that must not change, each with a reason), ## Verification (each item a command plus expected result).

Keep plans scannable yet executable without re-reading the conversation. Record only the chosen approach; rejected alternatives become one-line rationale under Key decisions.

Handoff plans: when another agent or session will execute, the executor has not seen this conversation. Inline any code excerpts and conventions it needs (with file:line markers), and add a STOP conditions section: assumptions that, if false, mean stop and report back rather than improvise.

Step 4: Validate

• Does the plan answer the user's original request?
• Did every interrogation answer land in the plan? An answer that never made it in was a wasted question.
• Scope gate: the plan fails if it violates any decision principle, especially an unneeded extension point, horizontal setup before the first tracer bullet, or a cut that drops required correctness, permissions, rollback, migration safety, or edge states.
• Any unstated assumptions that should be explicit?

Fix failures in the plan directly; don't reopen the interrogation. Report the plan path and confirm each check passed.

Step 5: Hand off

Offer Review: "Plan written to ``. Stress-test it to 5/5 before implementation?"

Review mode

Objective: drive all six dimensions to 5/5. Work each sub-5 dimension upward, re-scoring each round, until all are 5/5 or provably stalled on a decision only the user can make.

Review progress:
- [ ] Step 1: Load the plan
- [ ] Step 2: Triage: verify checkable claims, score all six dimensions
- [ ] Step 3: Rubber duck loop: drive each dimension  implementation -> `pr-reviewer` -> `pr-creator` -> `pr-babysitter`.

- `pr-reviewer`: code review after implementation; route here the moment the input is code, not a plan.
- `pr-creator`: opens the PR once the plan is implemented.
- `define-architecture`: architectural decisions that feed into plans.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [mblode](https://github.com/mblode)
- **Source:** [mblode/agent-skills](https://github.com/mblode/agent-skills)
- **License:** MIT
- **Homepage:** https://www.skills.sh/mblode/agent-skills

Install and usage instructions live in the source repository linked above.