| name | plan-first |
| description | Plan-mode enforcement — required before edits affecting 3+ files, cross-domain work, or security-sensitive changes |
| version | 0.2.0 |
| level | 2 |
| triggers | ["plan","plan mode","plan first","let's plan","/plan"] |
| context_files | ["context/user.md","context/principles.md"] |
| steps | [{"name":"Scope Assessment","description":"Count files, identify domains, flag security sensitivity. If editing a skill file, grep for its name across other skills to identify downstream dependents — list them in the plan so their behavior can be verified after the change."},{"name":"Plan Mode Decision","description":"If 3+ files, cross-domain, or security-sensitive — enter plan mode. State the decision explicitly."},{"name":"Decompose","description":"Break into ordered steps. Before writing each step, assess whether it carries hidden complexity not visible during scope scan. If yes, reason through it before writing the step. Max 5 sequential before a checkpoint."},{"name":"Identify Risks","description":"Flag irreversible operations, external calls, schema changes — each needs explicit confirmation"},{"name":"Parallel Opportunities","description":"Mark steps with no dependencies as parallel. Parallelizable steps do not count toward the 5-step limit."},{"name":"Confirm","description":"Present the plan. Wait for explicit user approval. Do not begin editing until confirmed."}] |
Plan-First Skill
Enforce plan-mode discipline before implementation.
What Claude Gets Wrong Without This Skill
Without plan-first, Claude begins editing immediately on complex tasks. Mid-task, it discovers dependencies it did not account for, requiring backtracking. On security-sensitive tasks, it makes changes whose scope only becomes visible after the fact. The cost of planning is always lower than the cost of unwinding a wrong approach.
When Plan Mode Is Required
| Condition | Plan Mode |
|---|
| 1-2 files, single domain | Optional |
| 3+ files | Required |
| Cross-domain | Required |
| Security-sensitive | Required |
| Schema / database changes | Required |
| Irreversible operations | Required |
Plan Format
## Plan: [task name]
### Scope
Files affected: [N] — [list]
Domains: [list]
Risk: LOW / MEDIUM / HIGH
### Steps
1. [action] — [file(s)]
2. [action] — [file(s)]
→ Parallel: [action] — [file(s)]
3. [action] — [file(s)]
↳ Checkpoint: verify [X] before proceeding
### Risks
[Risk] at Step [N] — requires [confirmation / rollback plan]
### Confirmation
Proceed? (yes / modify / no)
Checkpoint Rule
No more than 5 sequential steps without a verification checkpoint. At each:
- Run tests or build
- State expected outcome
- Decision: PIVOT / REFINE / PROCEED
Parallel steps that share no dependencies do not count toward the 5-step limit.
Anti-Patterns
Do not begin editing before the user says yes. "I'll start with step 1 while you review" is not compliant.
Do not present a plan so vague it cannot be critiqued. "Refactor the service" is not a step.
Do not include parallel steps that actually share file dependencies — race conditions are real even in sequential Claude sessions.
Mandatory Checklist
- Verify file count was assessed before deciding on plan mode
- Verify all 3 triggers were checked (files, domains, security)
- Verify each step names specific files, not "the relevant files"
- Verify parallel steps genuinely have no shared file dependencies
- Verify a checkpoint appears after every 5 sequential steps
- Verify the user explicitly confirmed before any editing began
