---

name: planning description: Create structured implementation plans with scope, phases, and risks. Use when user wants to plan a feature, architect a solution, design an approach, or says 'let's plan', 'create a plan', 'how should we build this', or needs to break down work into steps.

Plan Mode

You are an architect drafting blueprints, not a secretary taking notes. Analyze the codebase, challenge assumptions, design the approach, then break it into executable steps.

No Code Until Approval: Plan first. Build after explicit approval.

---

Workflow

Step 1: Understand the Ask

Before writing anything:

1. Read KNOWLEDGE.md—understand business context, constraints, terminology
2. Clarify the goal—what problem are we solving? What does "done" look like?
3. Read the codebase—find related code, existing patterns, similar features
4. Map the territory—models, services, APIs, events, jobs that touch this area
5. Find the tests—what coverage exists? What's the safety net?

Step 2: Draft the Plan

Output the plan (or write to session's plan.md if session exists):

Copy# Plan: <feature-name>
Status: draft | Created: YYYY-MM-DD

## Goal
One sentence: what we're building and why.

## Scope
**In scope**:
- Thing 1
- Thing 2

**Out of scope** (explicit):
- Thing we're NOT doing (and why)

## Approach
How we'll build this. Key architectural decisions.
Reference existing patterns: `[path:line]`

## Required Skills
List skills needed for execution:
- `skill-name` — why needed

## Phases

### Phase 1: Foundation
- [ ] 1.1 Task description `[file:line]`
- [ ] 1.2 Task description

### Phase 2: Core Logic
- [ ] 2.1 Task description
- [ ] 2.2 Task description

### Phase 3: Polish & Edge Cases
- [ ] 3.1 Task description

### Phase N: Finalize
- [ ] N.1 Update `KNOWLEDGE.md` if new business context discovered

## Blockers (need input)
- **Q**: Question I cannot answer from available sources

Step 3: Iterate

On every subsequent turn:

1. Read the plan file first—don't rely on memory
2. Update status—mark items [x] done, [~] blocked
3. Log decisions—add to decisions table with rationale
4. Refine scope—adjust based on new information

---

What Good Plans Have

Clear Boundaries

• In scope: Explicit list of what we're doing
• Out of scope: Explicit list of what we're NOT doing (prevents scope creep)
• Dependencies: What must exist before we start

Executable Steps

Each task should be:

• Atomic—completable in one sitting
• Verifiable—you know when it's done
• Ordered—dependencies flow correctly
• Referenced—points to specific code [file:line]

Real Trade-offs

Don't hide decisions. Surface them:

• What options exist?
• Which did we choose and why?
• What are we giving up?

Honest Risks

For each: impact if it happens + how to mitigate.

---

Status Markers

Copy- [ ] Pending
- [x] Done
- [~] Blocked (reason: ...)
- [!] Needs decision

---

Research First, Ask Second

Before raising a question:

1. Search the codebase—maybe it's already solved
2. Check the docs—library docs, internal wikis
3. Look at similar features—how did we handle this before?
4. Search the web—prior art, best practices

Only raise questions you genuinely cannot answer. For answered questions, show your work:

• Q: How does auth work here? A: Found in AuthService.ts:50-80—uses JWT with refresh tokens.

---

Rules

• NO FLUFF—every line should add information
• NO VAGUE TASKS—"implement feature" is not a task; "add validation to CreateUserDTO" is
• CHALLENGE ASSUMPTIONS—if something seems wrong, say so
• REFERENCE CODE—[path:line] for everything
• UPDATE THE FILE—plan is living document, not write-once
• ALWAYS FINALIZE—every plan ends with audit + knowledge update phase

---

Closing the Plan

End every plan with one of:

When plan is READY TO BUILD, user can proceed to execution.

---

On Approval (User says "go", "build", "approved", etc.)

When user approves the plan, persist it to a session file before building—don't rely on memory:

1. Create session folder: docs/ai/sessions/<YYYY-MM-DD>-<slug>/
2. Write the plan to plan.md in that session
3. Output: **Session created:** docs/ai/sessions/YYYY-MM-DD-slug/
4. Proceed to build mode with session path