planner-rules

Planner Rules

Task Classification

Classify task type before any research:

• new_feature: add, create, implement, new endpoint → typical M-XL
• bug_fix: fix, bug, broken, not working → typical S-M
• refactoring: refactor, rewrite, extract, split → typical M-L
• config_change: config, parameter, environment variable → typical S
• documentation: documentation, README, describe → typical S
• performance: optimization, slow, N+1, cache → typical M-L
• integration: external service, API call, client → typical L-XL

Complexity & Routing

Complexity	Parts	Layers	Route	Sequential Thinking	Plan Review
S	1	1	minimal	NOT needed	SKIP
M	2-3	2	standard	as needed	standard
L	4-6	3+	standard	RECOMMENDED	standard
XL	7+	4+	full	REQUIRED	standard

Auto-Escalation (re-routing)

• plan-review finds more Parts than expected → upgrade complexity
• coder finds hidden complexity (3+ adjustments) → upgrade + return to planner
• plan-review finds fewer Parts → downgrade complexity

Instructions

Step 1: Classify the task

Use Task Classification above to determine type (new_feature, bug_fix, etc.) and Complexity & Routing table for S/M/L/XL classification. Output: task type + complexity + route + ST requirement.

Step 2: Load required references

• ALWAYS load: MCP Tools
• Complexity L/XL: also load Sequential Thinking Guide
• Complexity M+: also load Data Flow
• For full classification details: Task Analysis

Step 3: Research with appropriate tools

• S/M: use Grep/Glob directly for codebase research
• L/XL: delegate to code-researcher agent via Task tool for multi-package research

Step 4: Document plan with full code examples

Write plan to .claude/prompts/{feature}.md using plan template. CRITICAL: Code examples must be FULL (complete function bodies), not just signatures. Form handoff payload for plan-review.

Example

Code completeness in plans

Principle: Full function body, error context propagated per ERROR_WRAP, explicit return types and values, no truncation.

Bad — signature-only stub (any language): Function declared without body (e.g. func Get(id string) error or def get(id): ...). Not actionable for the coder — no error path, no return shape.

Good — see per-language reference shapes in .claude/skills/planner-rules/code-shapes/<LANGUAGE>.md (resolved from PROJECT-KNOWLEDGE.md → LANGUAGE; falls back to code-shapes/_default.md pseudocode if LANGUAGE is unset or not one of go/python/typescript/rust/java).

Why: Incomplete examples are not actionable for the coder. Concrete shapes are language-specific; the four invariants (full body, ERROR_WRAP, explicit types, no truncation) are universal — see code-shapes/INVARIANTS.md.

For more examples, see Examples.

Common Issues

Plan has incomplete code examples

Cause: Planner shows function signature without body. Fix: RULE: Full Examples — all code in plan must have complete function bodies, error handling, and context propagation.

Sequential Thinking skipped for complex plan

Cause: Planner thinks plan is simple, but has 4+ parts. Fix: ALWAYS use Sequential Thinking if Parts >= 4, layers >= 3, or alternatives >= 3.

For all troubleshooting cases, see Troubleshooting.

Core Deps (loaded at startup)

• MCP Tools — Sequential Thinking, Context7 patterns and fallbacks
• Sequential Thinking Guide — when/how to use ST (complexity L/XL only, SKIP for S/M)

References

For detailed checks, read the supporting files in this skill directory:

• Task Analysis — full classification matrix, routing rules, preconditions, re-routing mechanism, examples
• Data Flow — data origin/path analysis, layer placement rules (SKIP for S, LOAD for M+)
• Examples — good vs bad code examples for plans
• Checklist — self-verification at each planner phase
• Troubleshooting — common planner issues and fixes
• code-researcher agent — available via Task tool for multi-package research (L/XL complexity, skip for S/M and --minimal)