dot_files/dot_claude/rules/planning.md

Planning (applies to ALL agents)

No implementation without completed research. This flow MUST run before implementation begins.

The approval gate at the end of planning is ExitPlanMode — there is no second user-gate step once the plan is accepted. See execution.md for what happens after approval.

Phase 1: Interview the User

Interview relentlessly. Make sure that all ambiguities are resolved before execution.

Before dispatching any researcher, ask targeted questions:

• What exactly should change? — not "add feature X" but the specific behavior expected
• What are the constraints? — backward compatibility, performance requirements, scope limits
• What should NOT change? — explicit out-of-scope items
• Who are the consumers? — who calls this code, who depends on it, who will be affected
• What edge cases worry you? — empty input, timeouts, stale data, concurrent access

Gates — do NOT proceed to Phase 2 until ALL of these are true:

• Every question has been answered by the user (not assumed)
• If any answer raised new questions, those were asked and answered too
• Zero ambiguity remains — you can describe the exact change without "probably", "maybe", "might"
• The user has not said "I'm not sure" about any critical decision — if they did, resolve it

Longer planning = fewer fixes later.

Phase 2: Code Exploration

Dispatch researcher subagents:

Mandatory investigations

Investigation	How	Blocker if skipped
All callers + blast radius	Claude Code Grep tool for references, IDE "find all references"	Cannot assess risk of change
Existing patterns + reusable code	Search for similar implementations before creating new	May duplicate existing utility
Edge cases + failure modes	Trace error handling paths, check null/empty/stale input	Bugs ship to production
Current data state	Query real data to understand current behavior with numbers	Assumptions may be wrong

For 2-3 parallel researchers

Researcher	Focus
R1: Existing code + patterns	Trace the code path being modified. Find all callers. Identify existing abstractions to reuse.
R2: Blast radius + dependencies	Who depends on this? Cross-team callers? What breaks if we change the interface?
R3: Data + edge cases	Query real data to validate assumptions. Identify failure modes.

For infra changes

If the work touches state described in infra/docs/architecture/ or infra/docs/runbooks/, read the relevant files BEFORE dispatching researchers. These docs are the authoritative starting point for current infra state — what's deployed, how it's wired, which conventions apply.

• infra/docs/architecture/ — long-lived state (networking, storage, auth, databases, CI/CD, monitoring, backup-dr, etc.)
• infra/docs/runbooks/ — operational procedures (restores, upgrades, recoveries)
• infra/docs/plans/ — dated design/plan pairs for prior changes; grep here first when a similar change has been done before
• infra/docs/post-mortems/ — incident analyses; relevant when work touches a past failure surface

If the docs contradict the live state, that mismatch is itself a finding — surface it and resolve before proceeding.

Phase 2b: Challenge, Verify, and Counter-Propose

Always required. After researchers report back, spawn 2 independent challenger subagents in parallel. Each works INDEPENDENTLY — they do NOT see each other's output.

Challenger mandate:

## Role: Independent Research Challenger

You are reviewing research findings. Your job has THREE parts:

### 1. Scrutinize
- Challenge the root cause analysis — what else could explain this?
- Question assumptions — what is assumed without evidence?
- Find missed edge cases — what happens with empty/null/stale/concurrent?
- Identify missing investigations — what callers/consumers were NOT checked?

### 2. Verify every reference
- For every FILE PATH cited: confirm it exists
- For every FUNCTION/CLASS cited: confirm it exists
- For every DATA CLAIM: confirm the data source exists and the query is valid
- Flag ANY reference that cannot be verified as UNVERIFIED

### 3. Counter-propose
- Propose at least ONE alternative approach to the problem
- Your alternative must ALSO be backed by verified code/data references
- Explain trade-offs: why your approach might be better or worse

Report:
- VERIFIED: claims you confirmed exist
- UNVERIFIED: claims you could not confirm
- ISSUES: genuine problems with the findings (not nitpicks)
- COUNTER-PROPOSAL: your alternative approach with references
- VERDICT: AGREE (approach is sound) or DISAGREE (significant issues remain)

Convergence check

After challengers return, evaluate:

1. Unverified claims — if any reference was flagged UNVERIFIED, dispatch a researcher to verify or remove it
2. Genuine issues — if challengers found real problems, dispatch a new research round → back to Phase 2b
3. Agreement — if both challengers AGREE the approach is sound, proceed to Phase 3
4. Counter-proposals — if a counter-proposal is clearly better, adopt it and re-validate

Never present unvetted findings to the user. All claims must be verified.

Phase 3: Resolve All Ambiguities

After researchers report back AND challengers have agreed on the approach:

1. List every open question — anything the researchers couldn't answer or disagreed on
2. Ask the user (via AskUserQuestion) to resolve each one — do NOT guess, do NOT assume
3. Present the plan via ExitPlanMode with:
   • Goal: what we're doing and why
   • Research Decisions: callers, blast radius, patterns to reuse, edge cases
   • Plan: ordered steps with checkboxes

ExitPlanMode is the approval gate. Once the user accepts, hand off to execution.md — no further "should I proceed?" check.

Research completeness checklist

Research is NOT complete if any of these are true:

• Callers were not traced
• No search for existing patterns
• Edge cases not identified
• Assumptions not validated with data
• Open questions remain
• No blast radius assessment
• References not verified (file paths, functions cited without confirming they exist)
• No challenge round completed
• Challengers did not agree

If any box is checked, research is incomplete. Go back and fill the gaps before surfacing a plan.