planning

Skill: planning

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

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

Thinking effort: Planning benefits from max effort. If not already at max, suggest the user increase it before proceeding.

Load Design Standards

Before any work: Read($CLAUDE_PLUGIN_ROOT/references/pre-gate-standards.md)

Create Progress Tasks

TaskCreate for each step, TaskUpdate with blockedBy to enforce ordering:

DISCOVER: Codebase search | DISCOVER: Questioning | CLASSIFY | EXPLORE | DETAIL | SAVE | CHECK | CONFIRM | HANDOFF

CHECK runs on all tracks — never skip independent review.

---

Step 1: DISCOVER

1a: Codebase Search (MANDATORY -- Do First)

Before asking ANY questions, load Skill(code-foundations:code-standards) to generate or update docs/code-standards.md. The skill handles staleness detection, codebase scanning, legacy migration, and writing.

See also: pattern-reuse-gate.md

1b: Clarify Intent

Load the clarify skill: Skill(code-foundations:clarify)

Use its framework to classify what's unclear (fault type + ambiguity direction) and generate targeted questions. Do not duplicate the questioning protocol here -- the skill has it.

Enforcement: Each question MUST use AskUserQuestion tool. No proceeding until answered. Short-circuit: zero questions if already clear.

Questioning Gate

STOP. Cannot proceed until ALL true:

• Codebase searched
• Complexity classified (Medium/Complex)
• Hypotheses converged (or request was already unambiguous)
• Each question asked via AskUserQuestion, each answer received

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 and re-confirm via AskUserQuestion: "Discovery found [X]. Updated problem statement: [Y]. Does this still capture what you want?"

---

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]." If uncertain, choose higher.

Track	Phases	Approach Comparison
Medium	3-5, ~100-150 words/phase	2 approaches
Complex	5-7, ~100-150 words/phase	2-3 + pre-mortem

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.

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)

Approach	Trade-offs	Best When	Research Source
Option A	[pros/cons]	[conditions]	[codebase/web]
Option B	[pros/cons]	[conditions]	[codebase/web]

Pre-Mortem (Complex Only)

Failure Mode	Probability	Impact	Which Approach Survives?
[failure]	LOW/MED/HIGH	LOW/MED/HIGH	[approach]

Recommendation + Decision Gate

After presenting the approach table, name a recommendation with 1-sentence rationale — not neutral presentation. The user wants an opinion, then picks.

MUST use AskUserQuestion with options:

• Each approach from the table (A, B, C...) as a selectable option
• "Elaborate on one" — expand trade-offs before choosing
• "Different direction" — none of the above fits

Hard gate: Cannot proceed to DETAIL until the user picks an approach via AskUserQuestion. Writing "Going with X" and moving on is a violation — the user must answer. No silent defaults, no "I'll flag it at confirm."

Question style: See adaptive-questioning.md. Encode the recommendation in the option labels (e.g., "Use JWT (recommended)") so confirmatory mode works inside the structured tool.

Record chosen approach, rationale, and fallback.

---

Step 4: DETAIL

The Plan Is a Contract

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

No implementation details in phases -- pre-gate writes pseudocode after fresh discovery. Plans must be pipeline-compatible -- deterministic rules, not interactive user prompts between sub-phases.

Phase Template

### Phase N: [Name]
**Model:** [recommended model]
**Skills:** [assigned at SAVE -- skills or `none -- [reason]`]

**Goal:** [One sentence (Simple) | 1-2 sentences (Medium/Complex)]

**Scope:**
- IN: [covered]
- OUT: [excluded]

**Constraints:** [non-discoverable requirements -- omit if none]

[Medium/Complex only]
**Approach notes:** [non-discoverable user decisions -- omit if none]
**File hints:** `path/` -- [why relevant]
**Depends on:** [Phase X] | **Unlocks:** [Phase Y]
[/Medium/Complex only]

**Done when:**
- [ ] DW-N.1: [verifiable criterion]

[Medium/Complex only]
**Difficulty:** LOW / MEDIUM / HIGH
**Uncertainty:** [what could change, or "None"]
[/Medium/Complex only]

DW-ID format: DW-{phase}.{item} -- every done-when item gets a stable ID.

Approach Notes

Only non-discoverable user decisions. Test: could codebase search find it? If yes, it does NOT belong.

• Good: "Use JWT not sessions -- user chose stateless for horizontal scaling"
• Bad: "Create a UserService class with getUser(), createUser()" (implementation detail)

YAGNI Gate + Phase Sizing

Before each phase: Is it needed for success criteria? Could we ship without it? If "not needed now" -> remove. Phase granularity test: each phase produces a deliverable meaningful to the orchestrator and verifiable by post-gate. If it's an internal component of another phase's deliverable, fold it in.

Phase counts: Medium 3-5, Complex 5-7. Prefer fewer. 200-word cap per phase. Express independent phases as DAG -- don't artificially linearize.

---

Step 5: SAVE

File Location

.code-foundations/plans/YYYY-MM-DD-<topic-slug>.md

Model Detection + Skill Assignment

Model detection per phase (MANDATORY -- every phase MUST have **Model:** populated):

OPUS_KEYWORDS  = [refactor, architect, migrate, redesign, rewrite, overhaul,
                  new abstraction, novel pattern, system design]
HAIKU_KEYWORDS = [config, rename, typo, bump, cleanup, delete, remove,
                  backfill, data fix, sql update, doc update]

DW items <= 2 AND file hints <= 1 area AND any HAIKU_KEYWORD   -> haiku
Any OPUS_KEYWORD OR (DW items >= 6 AND file hints >= 4 areas)  -> opus
Otherwise                                                       -> sonnet

Why Sonnet is the default, not omit: Omit means inherit the user's session model -- and plan tells the user to crank to max effort, so Opus propagates to every subagent. Most code-touching phases (test, fix, validate, implement, wire, helper, hook, integration) are mechanical translation work that runs faster and cheaper on Sonnet without measurable quality loss. Reserve Opus for the keyword-flagged design-heavy phases.

Skill assignment (EVERY phase MUST have **Skills:** field):

1. Scan system-reminder for all available skills (plugin:skill-name lines)
2. Match to phase goal, scope, and work type (tech stack, task type, domain)
3. Exclude workflow commands (plan, build, debug, research)
4. Write **Skills:** on every phase -- none -- [reason] valid, omission NOT valid

Plan File Schema

# Plan: [Topic]
**Created:** YYYY-MM-DD
**Status:** ready
**Complexity:** [simple/medium/complex]
---
## Context
[Problem statement from Step 1]
## Constraints
- [constraints]

[Medium/Complex only]
## Chosen Approach
**[Name]** -- [Rationale]. **Fallback:** [1 sentence]
## Rejected Approaches
- **[Name]:** [1 sentence why rejected]
[/Medium/Complex only]

---
## Implementation Phases
(Use phase template from Step 4)
---
## Test Coverage
**Level:** [100% / Backend only / Backend + frontend / None / Per-phase]
## Test Plan
- [ ] [tests] [Medium/Complex only] + Integration + Manual [/Medium/Complex only]

[Medium/Complex only]
## Assumptions
| Assumption | Confidence | Verify Before Phase | Fallback If Wrong |

## Decision Log
| Decision | Alternatives Considered | Rationale | Phase |
[/Medium/Complex only]

---
## Notes
- [edge cases, gotchas, open questions]
---
## Execution Log
_To be filled during /code-foundations:build_

Save (MANDATORY)

mkdir -p .code-foundations/plans, write plan file. Do NOT commit -- the plan is a working document, not a deliverable. Building handles worktree visibility by copying the plan file after worktree creation.

---

Step 6: CHECK

ALL tracks: Dispatch subagent to review saved plan with fresh eyes. Never skip — independent review catches blind spots regardless of task size.

Agent: sonnet, "Review plan"
Prompt: Review .code-foundations/plans/<plan>.md for structural issues.

Checklist:
- Structural: every constraint maps to a phase, done-when items cover problem statement,
  no scope overlap, union covers full feature, depends-on references exist, no orphan phases,
  approach notes only non-discoverable, file hints present, done-when observable + has DW-ID, YAGNI
- Coherence: no contradictions, Phase N output matches N+1 input,
  user-observable output exists, high-uncertainty phases early
- Skills: every phase has Skills field, skills match work type, skills actually available
- Models: every phase has Model field populated (haiku/sonnet/opus -- never omitted)

Output: PASS or FINDINGS with specific fix recommendations.

After return: PASS -> proceed. FINDINGS -> fix issues, then proceed.

---

Step 7: CONFIRM

Present to user: phases, goals, skill assignments, constraint coverage, review results.

Simple: "Does this look right? Anything to add or change?"

Medium/Complex: Structured summary with phases, constraint -> phase mapping, review results, remaining questions.

Question style: See adaptive-questioning.md. If the user has been terse during planning, present the plan with assumptions stated rather than asking open-ended "thoughts?"

Test Coverage (MANDATORY)

Ask: "How much test coverage?" Options: 100% (recommended), Backend only, Backend + frontend, None, Per-phase. Record in plan file under ## Test Coverage.

Corrections

If changes requested: update plan. Structural changes -> re-run CHECK. Minor changes -> update and re-present.

---

Step 8: HANDOFF

AskUserQuestion: "Plan saved. How would you like to proceed?"

1. Build now (Recommended) -- Suggest default thinking effort, run /code-foundations:build .code-foundations/plans/<plan>.md
2. Tell me what to do -- Numbered manual steps

Question style: See adaptive-questioning.md. The "Recommended" tag on Build now is the confirmatory cue — keep it there.

---

Chain

• Receives from: plan command (router dispatch)
• Chains to: build (via saved plan file)