planning

创建具有范围、阶段和风险的结构化实施计划。当用户想要规划功能、设计解决方案、设计方法或说“让我们规划”、“创建一个计划”、“我们该如何构建这个”或需要将工作分解为步骤时使用。

📖 中文导读:创建具有范围、阶段和风险的结构化实施计划。当用户想要规划功能、设计解决方案、设计方法或说“让我们规划”、“创建一个计划”、“我们该如何构建这个”或需要将工作分解为步骤时使用。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

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:

  1. Use the provided session path
  2. Read existing README.md, workshop.md for context
  3. Write plan to session's plan.md

If NO session path provided — CREATE ONE:

  1. Generate slug from task description (e.g., "add user auth" → user-auth)
  2. Create folder: docs/ai/sessions/<YYYY-MM-DD>-<slug>/
  3. Create README.md with:
    # Session: <Task Title>
    
    **Status:** planning
    **Created:** YYYY-MM-DD
    
    ## Context
    <Brief description of what we're building and why>
    
    ## Files
    - plan.md — Implementation plan
    
  4. 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:

  1. Clarify the goal—what problem are we solving? What does "done" look like?
  2. Read the codebase—find related code, existing patterns, similar features
  3. Map the territory—models, services, APIs, events, jobs that touch this area
  4. 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:

  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

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:

  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

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>