ryanthedev/code-foundations/planning

Skill: planning

Standard/Full planning pipeline: Discover -> Classify -> Explore -> Decompose -> Detail -> Cross-cut -> Save -> Check -> Confirm -> Handoff

The plan is written in stages, not one shot: DECOMPOSE fixes the phase shape and seams, DETAIL fills one phase at a time with a reset between each, CROSS-CUT derives the whole-plan sections. Each stage writes to the file in place.

The plan is a contract between plan and build. It specifies WHAT and WHY at the strategic level, with explicit interfaces between phases.

User-facing output stays terse. Only three steps run a full checkpoint — a structured render that ends the turn and waits for a reply: EXPLORE's decision gate, the Skeleton Checkpoint, and CONFIRM. A brief one-sentence declaration (CLASSIFY's verdict, a demotion notice) can still surface inline, immediately followed by the next step's work in the same turn — but it stays one sentence, never a restated deliberation trail. Everything else — DISCOVER's gate, DETAIL's per-phase reset — is internal bookkeeping the user never sees. If a step's output reads like a transcript of the reasoning ("X confirmed... Y confirmed... this matches the prior call"), it's wrong regardless of which step produced it.

Thinking effort: Planning is where the reasoning lives — it benefits from high effort. If the session is running lower, suggest the user increase it before proceeding. (Build runs the other way: low for all-serial plans, default for wave plans — see references/plan-integration.md.)

Create Progress Tasks

TaskCreate one task per pipeline step (the ten named in the header line above), TaskUpdate with blockedBy to enforce ordering:

DISCOVER | CLASSIFY | EXPLORE | DECOMPOSE | DETAIL | CROSS-CUT | SAVE | CHECK | CONFIRM | HANDOFF

During DETAIL, add one sub-task per phase under it (one TaskCreate each), worked in DAG order.

At user checkpoints (EXPLORE decision gate, Skeleton Checkpoint, CONFIRM) the rendered artifact is the turn's final message — complete the step's task at the start of the next turn, after the user answers, so the bookkeeping never trails the presentation.

CHECK runs on all tracks — never skip independent review.

Step 1: DISCOVER

DISCOVER runs after the plan command's shared steps (code-standards scan, clarify, confirmed problem statement). Do NOT re-run them. This step is the delta: deepen codebase research, and re-confirm the problem statement only if discovery contradicts it.

1a: Deepen Codebase Research

The code-standards scan already ran in the plan command's shared step 1 — docs/code-standards.md exists. Do not reload the code-standards skill. Deepen the research instead: how similar problems are solved here, existing libraries/patterns to reuse, and patterns intentionally omitted (check git history).

1b: Re-confirm Problem Statement (only on contradiction)

A confirmed problem statement already arrives from the plan command's shared step — clarification ran there, under its 5-round cap. Do not reload the clarify skill or re-clarify from scratch. Only if deeper research contradicts or materially broadens the stated problem do you re-confirm (see Output below).

Gate (internal check, not narrated to the user) — proceed to CLASSIFY only when all three hold

• [ ] Codebase research deepened (pattern reuse + prior art checked)
• [ ] Track received from dispatch (Medium/Complex)
• [ ] Problem statement holds, or was re-confirmed after a discovery contradiction

Output: Problem Statement

A confirmed problem statement arrives from the shared steps in the plan command. DISCOVER refines it with deeper codebase context — don't redo clarification from scratch.

Review the existing problem statement against what deeper discovery found. If it holds, proceed. If discovery reveals the problem is different or broader than stated, update it, render the updated statement as markdown in conversation, and end the turn asking: "Discovery found [X]. Does the updated statement still capture what you want?" — [X] is a short phrase naming what changed, not a restatement of the discovery research; the updated statement itself carries the detail. Content confirmations happen in conversation, where the full statement is visible (see Channel Selection in adaptive-questioning.md).

Step 2: CLASSIFY

Classify using signals: files touched (Medium 4-8, Complex 9+), patterns (Medium 2-3 some new, Complex multiple cross-cutting), cross-cutting concerns (Medium 1-2, Complex 3+), uncertainty (Medium approach unclear, Complex requirements uncertain), phase count (Medium 3-5, Complex 5-7).

State explicitly: "This is a [Medium/Complex] task. [1-sentence justification]." This sentence surfaces inline — it isn't its own checkpoint — and leads straight into EXPLORE's research in the same turn. If uncertain between Medium and Complex, choose higher (this tie-breaker refines Medium-vs-Complex only; the plan command's "Default to Quick" already routed the task here).

Demotion path — discovery reveals the task is actually Simple: if the signals now read Simple (one focused change, 1-2 phases, no approach comparison needed), stop the pipeline and hand back to the Quick track in commands/plan.md. Do not force a 3-phase plan onto a one-thing change. Say so explicitly: "Discovery shows this is a Simple task — switching to the Quick track."

Hard cap: 7 phases. More than 7 -> split into multiple plans.

Step 3: EXPLORE

Research BEFORE proposing -- uninformed proposals waste the user's decision-making.

Load Design Vocabulary

Skill(code-foundations:ca-architecture-boundaries) — system-level vocabulary (boundaries, dependency direction, SRP-by-actor) for generating structurally different approaches here and shaping phase seams at DECOMPOSE. Module-level design skills (e.g. aposd-designing-deep-modules) are NOT loaded here — they get matched per phase at DECOMPOSE and loaded during DETAIL.

Research (Medium/Complex)

Codebase: How similar problems are solved, existing libraries/patterns, intentionally omitted patterns (check git history).

Web (when technology choice is involved): Compare libraries/frameworks, check current best practices. Search for "[tech A] vs [tech B] [year]", "[domain] best practices [year]".

Generate Alternatives

Approaches must be structurally different (different technology, pattern, or architecture):

• Good: "JWT tokens" vs "Session cookies" vs "OAuth2"
• Bad: "JWT with refresh" vs "JWT without refresh" (same approach)

Everything about an approach lives in its row — no prose paragraph per approach before or after the table. One clause per cell; if a cell needs two sentences, the approach isn't simple enough yet. Source is a short tag (a file or pattern name), not a citation sentence.

Pre-Mortem (Complex Only)

Recommendation + Decision Gate

Open directly with the table — no restating CLASSIFY or DISCOVER's conclusions first; those already happened, and the user needs the fork, not the trail that led to it. End the turn with the approach comparison rendered as markdown in conversation — the full table (what, trade-offs, best-when, research source per approach; pre-mortem for Complex) — then name a recommendation with 1-sentence rationale (not neutral presentation; the user wants an opinion) and ask which approach to take. The comparison must be the turn's final message, with no tool calls after it: an approach comparison is a content review, and the conversation is the only surface that renders it in full (see Channel Selection in adaptive-questioning.md).

The user answers free-form — an approach name, "your recommendation", or a different direction entirely.

Gate: DETAIL starts only after the user has picked. Writing "Going with X" and moving on skips the decision that anchors every phase body — the user must answer. If they've been terse, apply confirmatory mode: lead with "I'll go with [X] unless you'd rather one of the others."

Record chosen approach, rationale, and fallback — held in conversation until DECOMPOSE writes them into the plan file's ## Chosen Approach (the file doesn't exist yet).

Step 4: DECOMPOSE

Get the shape right before investing in phase bodies. Write the skeleton only — no internals yet.

The Plan Is a Contract

The plan specifies WHAT and WHY. Subagents determine HOW. Four readers: orchestrator (phase names, ordering, DW counts), build-agent (goal, scope, constraints, approach notes, file hints), post-gate-agent (goal, done-when), human (strategic intent, rationale).

No implementation details in phases -- the build-agent writes pseudocode after fresh discovery. Cross-phase seams are the one exception: the Produces contract pins the interface; internals stay the build agent's latitude. Plans must be pipeline-compatible -- deterministic rules, not interactive user prompts between sub-phases.

Define the Phases as a DAG

For each phase, write only:

• Name + one-line goal
• Depends on / Unlocks — the edges
• Produces: what this phase hands the phase(s) that consume it — the explicit seam. This is the interface the contract promises; designing it now is exactly what one-shotting skips.
• Skills: matched now so DETAIL can load them (see below)
• Difficulty: LOW / MEDIUM / HIGH

Match Skills per Phase

Skills are matched HERE so DETAIL can load them while writing phase bodies — a phase body written without domain knowledge is the planner guessing.

1. Match against your available-skills register — every skill whose description is in context. That includes the 18 matchable internal code-foundations skills (user-invocable: false: model-discoverable, hidden from the slash menu; planning itself is excluded — disable-model-invocation keeps it out of the register) AND skills from other installed plugins (e.g. skill-craft, mcp-builder, security-guidance). Each description carries its own when-to-match and sibling-disambiguation (the "not for X (use Y)" clauses) — match on the descriptions directly.
2. For each phase, compare the phase's goal against every candidate skill's when-to-match conditions (register descriptions for external skills; catalog entries plus their disambiguation notes for the internal sibling pairs)
3. Assign skills whose triggers match the phase work. Most phases match 1-3 skills.
4. Exclude workflow commands and pipeline skills (plan, build, debug, research, code-standards, clarify, planning)
5. Write **Skills:** on every skeleton header — none -- [reason] valid, omission NOT valid

`none` is the exception, not the default. If a phase writes code, designs an API, refactors, handles errors, touches control flow, or modifies existing untested code — there is almost certainly a matching skill. DETAIL may add skills it discovers while writing bodies; SAVE validates the final set.

YAGNI Gate + Phase Sizing