planning
创建具有范围、阶段和风险的结构化实施计划。当用户想要规划功能、设计解决方案、设计方法或说“让我们规划”、“创建一个计划”、“我们该如何构建这个”或需要将工作分解为步骤时使用。
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 Chat Output: ALL responses go to the plan file only. No Code Until Approval: Plan first. Build after explicit approval.
Workflow
Step 0: Session Setup (REQUIRED)
Planning ALWAYS requires a session to track state. Sessions enable /loop for autonomous execution.
If session path provided:
- Use the provided session path
- Read existing
README.md,workshop.mdfor context - Write plan to session's
plan.md
If NO session path provided — CREATE ONE:
- Generate slug from task description (e.g., "add user auth" →
user-auth) - Create folder:
docs/ai/sessions/<YYYY-MM-DD>-<slug>/ - Create
README.mdwith:# Session: <Task Title> **Status:** planning **Created:** YYYY-MM-DD ## Context <Brief description of what we're building and why> ## Files - plan.md — Implementation plan - Output session path clearly:
Session created:
docs/ai/sessions/YYYY-MM-DD-slug/Use
/loop docs/ai/sessions/YYYY-MM-DD-slug/to start autonomous execution after plan approval.
Step 1: Understand the Ask
Before writing anything:
- Clarify the goal—what problem are we solving? What does "done" look like?
- Read the codebase—find related code, existing patterns, similar features
- Map the territory—models, services, APIs, events, jobs that touch this area
- Find the tests—what coverage exists? What's the safety net?
Step 2: Draft the Plan
Write to session's plan.md:
# 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]`
## 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
> **Between phases**: Compact context before starting the next phase. Summarize what was done, drop implementation details, keep only what's needed for remaining work.
## Blockers (need input)
- **Q**: Question I cannot answer from available sources
Step 3: Iterate
On every subsequent turn:
- Read the plan file first—don't rely on memory
- Update status—mark items
[x]done,[~]blocked - Log decisions—add to decisions table with rationale
- 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
| Category | Examples |
|---|---|
| Technical | Race conditions, data migration, breaking changes |
| Integration | Third-party APIs, other teams' code |
| Unknown | Unfamiliar area, no tests, magic code |
| Scope | Feature creep, unclear requirements |
For each: impact if it happens + how to mitigate.
Status Markers
- [ ] Pending
- [x] Done
- [~] Blocked (reason: ...)
- [!] Needs decision
Research First, Ask Second
Before raising a question:
- Search the codebase—maybe it's already solved
- Check the docs—library docs, internal wikis
- Look at similar features—how did we handle this before?
- 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
Closing the Plan
End every plan with one of:
| Status | Meaning |
|---|---|
| READY TO BUILD | Plan is complete, no blockers, approved to execute |
| DECIDE FIRST | Need decision on: [specific thing] |
| BLOCKED | Cannot proceed until: [specific blocker] |
| NEEDS REFINEMENT | More research/discussion needed on: [area] |
When plan is READY TO BUILD, remind user:
To start autonomous execution:
/loop <session-path>