planner-workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Planner Phase Workflow

Planner阶段工作流

You have been assigned a planning task to create a full plan with phases for a feature. Your spawn prompt contains the feature description, requirements, and plan folder path. This skill teaches you how to handle the entire planning process end-to-end.

你已被分配一项规划任务，需要为某个功能创建包含多个阶段的完整规划。你的生成提示中包含功能描述、需求和规划文件夹路径。本skill将教你如何端到端处理整个规划流程。

Why This Workflow Exists

本工作流的设计初衷

The user experienced planners that guessed at patterns, skipped template sections, and produced phases with generic code blocks. Each step below prevents a specific failure:

Step	Prevents
Read templates completely	Missing required sections, rework during review
Create task list	Lost progress after context compact, skipped phases
Read codebase references	Code blocks that don't match real project patterns
Checkpoint 1 (plan summary)	Building 20 phases on wrong assumptions — hours wasted
Self-validate each phase	Placeholder content and missing TDD discovered late in review

过往用户遇到的规划器存在凭经验猜测模式、跳过模板章节、输出的阶段仅包含通用代码块等问题。以下每个步骤都对应解决一类特定故障：

步骤	避免的问题
完整读取模板	缺失必填章节，评审阶段返工
创建任务列表	上下文压缩后进度丢失、跳过阶段
读取代码库引用	代码块不符合实际项目模式
检查点1（规划概要）	基于错误假设构建20个阶段，浪费数小时时间
每个阶段自校验	评审后期才发现占位内容和缺失的TDD环节

Step 1: Read Templates

步骤1：读取模板

The user created these templates specifically so phases don't miss required sections. Skipping template reading causes incomplete phases that require rework during implementation.

Read both templates completely:

$CLAUDE_PROJECT_DIR/.claude/skills/create-plan/references/PLAN-TEMPLATE.md

$CLAUDE_PROJECT_DIR/.claude/skills/create-plan/references/PHASE-TEMPLATE.md

Every section in these templates is required. Extract the section lists — you'll use them as checklists when writing plan.md and phase files.

用户专门创建了这些模板，避免阶段缺失必填章节。跳过模板读取会导致阶段内容不完整，在落地阶段需要返工。

请完整读取两个模板：

$CLAUDE_PROJECT_DIR/.claude/skills/create-plan/references/PLAN-TEMPLATE.md

$CLAUDE_PROJECT_DIR/.claude/skills/create-plan/references/PHASE-TEMPLATE.md

这些模板中的每个章节都是必填项。请提取章节列表，后续编写plan.md和阶段文件时将其作为核对清单使用。

Step 2: Create Folder Structure

步骤2：创建文件夹结构

Folder naming pattern:

plans/{YYMMDD}-{feature-name}/

Examples:

```
plans/260220-voice-assistant/
```
```
plans/260220-notification-system/
```

Create these items:

Main folder:
```
plans/{YYMMDD}-{feature-name}/
```

Planning reviews folder:

plans/{YYMMDD}-{feature-name}/reviews/planning/

Code reviews folder:

plans/{YYMMDD}-{feature-name}/reviews/code/

文件夹命名规则：

plans/{YYMMDD}-{feature-name}/

示例：

```
plans/260220-voice-assistant/
```
```
plans/260220-notification-system/
```

创建以下内容：

主文件夹：
```
plans/{YYMMDD}-{feature-name}/
```

规划评审文件夹：

plans/{YYMMDD}-{feature-name}/reviews/planning/

代码评审文件夹：

plans/{YYMMDD}-{feature-name}/reviews/code/

Step 3: Create Task List

步骤3：创建任务列表

Tasks survive context compacts — skipping this check causes duplicate tasks and lost progress.

Before creating tasks, run

TaskList

to check if tasks already exist from a previous session or before a compact. If tasks exist:

Read existing tasks with
```
TaskGet
```
for each task ID
Find the first task with status
```
pending
```
or
```
in_progress
```
Resume from that task — do NOT recreate the task list

If no tasks exist, create them now. Prefix all task subjects with
[Plan]
to distinguish from the orchestrator's tasks in the shared team task list.

Example task list:

[Plan] Create plan.md scaffold (all sections except Phase Table content)
[Plan] Read codebase references
[Plan] Checkpoint 1 — report plan summary to orchestrator
[Plan] Create Phase 01 - [Title]
[Plan] Create Phase 02 - [Title]
[...continue for all phases...]
[Plan] Checkpoint 2 — report completion to orchestrator

Mark each task

in_progress

before starting and

completed

when done via

TaskUpdate

任务不会随上下文压缩丢失——跳过此检查会导致任务重复、进度丢失。

创建任务前，先运行

TaskList

检查是否存在上一会话或上下文压缩前遗留的任务。如果已有任务：

对每个任务ID运行
```
TaskGet
```
读取现有任务
找到第一个状态为
```
pending
```
或
```
in_progress
```
的任务
从该任务继续推进——不要重新创建任务列表

如果没有现有任务，请立即创建。所有任务主题前缀需添加
[Plan]
，以在共享团队任务列表中与orchestrator创建的任务区分开。

示例任务列表：

[Plan] Create plan.md scaffold (all sections except Phase Table content)
[Plan] Read codebase references
[Plan] Checkpoint 1 — report plan summary to orchestrator
[Plan] Create Phase 01 - [Title]
[Plan] Create Phase 02 - [Title]
[...continue for all phases...]
[Plan] Checkpoint 2 — report completion to orchestrator

启动每个任务前通过

TaskUpdate

标记为

in_progress

，完成后标记为

completed

。

Step 4: Read Codebase References

步骤4：读取代码库引用

Code blocks written from memory often don't match the real codebase — this is the #1 source of phase quality issues. Reading actual files before writing phases ensures patterns are accurate.

Identify which file types the feature will need and read one reference for each:

Feature Needs	Reference to Read
Server actions	Glob `app/home/[account]/*/server-actions*.ts` → read one
Service layer	Glob `app/home/[account]/*/service*.ts` → read one
Zod schemas	Glob `app/home/[account]/*/.schema.ts` → read one
SQL migrations / RLS	Glob `supabase/migrations/*.sql` → read a recent one
React components	Glob `app/home/[account]/*/_components/.tsx` → read one
Page files	Glob `app/home/[account]/**/page.tsx` → read one
Tests	Glob `__tests__/*/.test.ts` → read one

Key patterns to extract and use in phase code blocks:

Server action pattern:
```
'use server'
```
+ Zod parse +
```
getSession()
```
auth check

Account resolution: slug → ID via

client.from('accounts').select('id').eq('slug', data.accountSlug).single()

Permission check: your RLS helper function (e.g.,
```
client.rpc('check_account_access', { ... })
```
)
Supabase client:
```
createClient()
```
from
```
@/lib/supabase/server
```

Service factory:

createXxxService(client: SupabaseClient<Database>)

wrapping a private class

Import paths:
```
import 'server-only'
```
,
```
@/
```
path alias for project root
File naming:
```
_lib/schema/
```
(singular),
```
server-actions.ts
```
, exports ending in
```
Action
```
TypeScript: consider enums or union types for constants,
```
interface
```
preferred for objects
After mutations:
```
revalidatePath('/home/[account]/...')
```

凭记忆编写的代码块往往不符合实际代码库规范——这是阶段质量问题的首要来源。编写阶段前读取实际文件可确保模式准确。

确定功能需要用到的文件类型，每类读取一个参考文件：

功能需求	读取的参考文件
Server actions	全局匹配 `app/home/[account]/*/server-actions*.ts` → 读取一个
服务层	全局匹配 `app/home/[account]/*/service*.ts` → 读取一个
Zod schemas	全局匹配 `app/home/[account]/*/.schema.ts` → 读取一个
SQL 迁移 / RLS	全局匹配 `supabase/migrations/*.sql` → 读取最近的一个
React 组件	全局匹配 `app/home/[account]/*/_components/.tsx` → 读取一个
页面文件	全局匹配 `app/home/[account]/**/page.tsx` → 读取一个
测试用例	全局匹配 `__tests__/*/.test.ts` → 读取一个

需提取并在阶段代码块中使用的核心模式：

Server action 模式：
```
'use server'
```
+ Zod 解析 +
```
getSession()
```
权限校验

账户解析：通过

client.from('accounts').select('id').eq('slug', data.accountSlug).single()

将slug转换为ID

权限校验：你的RLS辅助函数（例如
```
client.rpc('check_account_access', { ... })
```
）
Supabase 客户端：从
```
@/lib/supabase/server
```
引入的
```
createClient()
```

服务工厂：包装私有类的

createXxxService(client: SupabaseClient<Database>)

导入路径：
```
import 'server-only'
```
，项目根路径别名
```
@/
```
文件命名：
```
_lib/schema/
```
（单数）、
```
server-actions.ts
```
，导出内容以
```
Action
```
结尾
TypeScript：常量优先使用枚举或联合类型，对象优先使用
```
interface
```
定义
变更操作后：执行
```
revalidatePath('/home/[account]/...')
```

Pre-Implementation Analysis

落地前分析

Before scoping phases, run through the checklist in

.claude/rules/pre-implementation-analysis.md

. Its 7 dimensions — existing patterns, blast radius, security surface, performance, maintainability, multi-tenant safety, and upstream compatibility — directly inform phase boundaries and what each phase's

Prerequisites & Clarifications

section should cover. Findings from this analysis (e.g. "touches auth flow", "new table needs RLS") should surface in the relevant phase files, not be left implicit.

在划定阶段范围前，通读

.claude/rules/pre-implementation-analysis.md

中的核对清单。其7个维度——现有模式、影响范围、安全面、性能、可维护性、多租户安全性、上游兼容性——会直接影响阶段边界划分，以及每个阶段的

Prerequisites & Clarifications

章节需要覆盖的内容。该分析的结论（例如「涉及鉴权流程」「新表需要配置RLS」）应当在对应阶段文件中明确体现，不要隐式省略。

Frontend Guidelines (If Applicable)

前端规范（如适用）

If the feature involves React components, Next.js pages, or UI work, invoke this skill BEFORE designing phases:

/vercel-react-best-practices

This loads 57 performance rules across 8 categories. Reference these when designing data fetching patterns, component architecture, and bundle optimisation requirements.

Keep these patterns in mind for every code block you write in phase files. The review step will flag any code blocks that deviate from these codebase patterns.

如果功能涉及React组件、Next.js页面或UI工作，在设计阶段前先调用此skill：

/vercel-react-best-practices

该skill包含8个类别共57条性能规则，设计数据拉取模式、组件架构、包体积优化要求时请参考这些规则。

在阶段文件中编写的每个代码块都要牢记这些模式，评审环节会标记出所有不符合代码库模式的代码块。

Step 5: Create plan.md

步骤5：创建plan.md

Write

plans/{folder}/plan.md

with ALL sections from the template:

YAML Frontmatter (title, status, priority, tags, dates)
Executive Summary (Mission, Big Shift, Deliverables)
Phasing Strategy (Phase Constraints, Phase File Naming)
Phase Table — Header row only, no content rows yet
Architectural North Star (patterns with Core Principle + Enforcement)
Component Library Priority (check your UI library before building custom)
Security Requirements (RLS, Input Validation, Authorization, Error Handling)
Implementation Standards (Test Strategy, Documentation Standard)
Success Metrics & Quality Gates
Global Decision Log (ADRs)
Resources & References

Complete ALL sections except Phase Table rows. Missing sections are caught during review but cost extra review cycles to fix.

编写

plans/{folder}/plan.md

，包含模板中的所有章节：

YAML 头部信息（标题、状态、优先级、标签、日期）
执行概要（使命、核心变更、交付物）
分阶段策略（阶段约束、阶段文件命名规则）
阶段表 —— 仅表头，暂不填充内容行
架构核心准则（包含核心原则+落地要求的模式）
组件库优先级（构建自定义组件前先核对UI组件库）
安全要求（RLS、输入校验、授权、错误处理）
落地标准（测试策略、文档规范）
成功指标与质量门禁
全局决策日志（ADRs）
资源与参考

完成除阶段表行之外的所有章节。缺失章节会在评审中被发现，但会消耗额外的评审周期修复。

Phase Constraints

阶段约束

Phases that exceed one context window cause Claude to lose earlier context mid-implementation, producing incomplete or inconsistent code. Each phase should be atomic enough for implementation in 1 context window (~15KB document, ~2-3 hour focused session).

30 small phases > 5 large phases

Wrong Approach	Right Approach
"Phase 01: Database + API + UI"	Split into 3 phases
"Phase 02: Full Feature Implementation"	Break into atomic steps
"Phase 03: Testing and Polish"	TDD is Step 0 in EACH phase

TDD Note: Both backend and frontend code require full unit tests:

Backend (services, schemas, APIs): Unit tests in
```
__tests__/{feature}/
```
Frontend (React/TSX): Component tests using happy-dom (default) and @testing-library/react
The default happy-dom environment works for component tests. Only add
```
// @vitest-environment happy-dom
```
if explicitly overriding another environment.
Use
```
it.todo('description')
```
for TDD stubs
Use
```
vi.hoisted()
```
for mock variables needed before module evaluation
For Supabase client mocks, add
```
.then()
```
method for thenable/awaitable pattern
Path aliases in tests: use your project's configured path alias (e.g.,
```
@/
```
or
```
~/
```
)

The test: Can Claude implement this phase without running out of context? If unsure, split it.

超过单个上下文窗口的阶段会导致Claude在落地过程中丢失早期上下文，生成不完整或不一致的代码。每个阶段应当足够原子，可在1个上下文窗口内完成落地（约15KB文档，约2-3小时专注工作）。

30个小阶段远优于5个大阶段

错误做法	正确做法
"阶段01：数据库 + API + UI"	拆分为3个阶段
"阶段02：完整功能落地"	拆分为原子步骤
"阶段03：测试与优化"	TDD是每个阶段的第0步

TDD注意事项： 后端和前端代码都需要完整的单元测试：

后端（服务、schema、API）：单元测试放在
```
__tests__/{feature}/
```
目录下
前端（React/TSX）：使用happy-dom（默认）和@testing-library/react编写组件测试
默认的happy-dom环境可满足组件测试需求，仅在需要覆盖其他环境时添加
```
// @vitest-environment happy-dom
```
TDD桩代码使用
```
it.todo('description')
```
模块求值前需要的 mock 变量使用
```
vi.hoisted()
```
Supabase客户端mock需要添加
```
.then()
```
方法适配thenable/awaitable模式
测试中的路径别名：使用项目配置的路径别名（例如
```
@/
```
或
```
~/
```
）

校验标准： Claude能否在不超出上下文的前提下完成该阶段落地？如果不确定，就拆分阶段。

Step 6: Checkpoint 1 — Report Plan Summary

步骤6：检查点1 —— 提交规划概要

After creating plan.md, report to the orchestrator for user review. This is the key benefit of the team pattern — the user can course-correct before you spend time writing 15 phase files.

SendMessage({
  type: "message",
  recipient: "team-lead",
  content: `## Plan Summary — Ready for Review

**Feature**: {feature name}
**Plan folder**: plans/{YYMMDD}-{feature-name}/

创建完plan.md后，向orchestrator提交报告等待用户评审。这是团队协作模式的核心优势——用户可以在你花费时间编写15个阶段文件前修正方向。

SendMessage({
  type: "message",
  recipient: "team-lead",
  content: `## Plan Summary — Ready for Review

**Feature**: {feature name}
**Plan folder**: plans/{YYMMDD}-{feature-name}/

Executive Summary

{1-2 sentence mission}

Proposed Phase Breakdown

#	Title	Group	Skill	Dependencies
01	{title}	{group}	{skill}	None
02	{title}	{group}	{skill}	Phase 01
...

#	Title	Group	Skill	Dependencies
01	{title}	{group}	{skill}	None
02	{title}	{group}	{skill}	Phase 01
...

Group Summary

Group	Phases	Description
{name}	P01-P03	{what this group delivers}

Group	Phases	Description
{name}	P01-P03	{what this group delivers}

Architecture Decisions

{key decision 1}
{key decision 2}

{key decision 1}
{key decision 2}

Security Requirements

{key requirement}

Awaiting approval or feedback before creating phase files.`, summary: "Plan summary ready for review" })


**Then WAIT.** Do not proceed to Step 7 until the orchestrator responds with approval or feedback.

- **If approved:** Continue to Step 7.
- **If changes requested:** Revise plan.md and the phase breakdown, then re-send the summary. Repeat until approved.

{key requirement}

Awaiting approval or feedback before creating phase files.`, summary: "Plan summary ready for review" })


**之后请等待。** 在orchestrator返回批准或反馈前，不要进入步骤7。

- **如果获批：** 继续步骤7
- **如果要求修改：** 修订plan.md和阶段拆分，重新提交概要，重复流程直到获批。

Step 7: Create Phases (Iterative)

步骤7：迭代创建阶段

For EACH phase, in order:

按顺序为每个阶段执行以下操作：

7a: Add Row to Phase Table

7a：在阶段表中添加行

Edit

plan.md

to add the phase row:

markdown

| **01** | [Title](./phase-01-slug.md) | [group-name] | [Focus] | Pending |

编辑

plan.md

添加阶段行：

markdown

| **01** | [Title](./phase-01-slug.md) | [group-name] | [Focus] | Pending |

7b: Create Phase File

7b：创建阶段文件

Write the complete phase file following PHASE-TEMPLATE.md exactly.

File:

plans/{folder}/phase-{NN}-{slug}.md

Include
skill
in Frontmatter — without it, the implementer won't know which skill to invoke and will use generic patterns instead of project-specific ones.

Phase Type	Skill Value
Database schema, migrations, RLS	`postgres-expert`
Server actions, services, API	`server-action-builder`
React forms with validation	`react-form-builder`
E2E tests	`playwright-e2e`
React components/pages	`vercel-react-best-practices`
UI/UX focused work	`web-design-guidelines`

Example frontmatter:

yaml

---
title: "Phase 01 - Database Schema"
skill: postgres-expert
status: pending
group: "auth-system"
dependencies: []
---

Group assignment rules:

Connected phases building the same feature/component MUST share a
```
group:
```
name
Group names should be descriptive:
```
auth-system
```
,
```
dashboard-ui
```
,
```
data-pipeline
```
Single-phase groups are valid for standalone work
Groups define audit boundaries — after all phases in a group complete during implementation, an auditor reviews them together
Order groups so dependencies flow top-to-bottom (group A before group B if B depends on A)

For phases spanning multiple concerns, list the primary skill or use comma-separated values:

yaml

skill: react-form-builder, vercel-react-best-practices

Required sections (from template):

YAML Frontmatter (title, description, status, dependencies, tags, dates, skill)
Overview (brief description, single-sentence Goal)
Context & Workflow (How the Project Uses This, User Workflow, Problem Being Solved)
Prerequisites & Clarifications (Questions for User with Context/Assumptions/Impact)
Requirements (Functional + Technical)
Decision Log (phase-specific ADRs)
Implementation Steps — Step 0: TDD is first
Verifiable Acceptance Criteria (Critical Path, Quality Gates, Integration)
Quality Assurance (Manual Testing, Automated Testing, Performance Testing, Review Checklist)
Dependencies (Upstream, Downstream, External)
Completion Gate (Sign-off checklist)

Code blocks in phases should match codebase patterns from Step 4 — not memory, not generic examples. Generic code blocks cause the implementer to write code that doesn't follow project conventions, creating rework. If you don't remember the exact pattern, re-read the reference file from Step 4 before writing the code block.

严格遵循PHASE-TEMPLATE.md编写完整的阶段文件。

文件路径：

plans/{folder}/phase-{NN}-{slug}.md

在头部信息中添加
skill
字段——没有该字段的话，落地人员不知道要调用哪个skill，会使用通用模式而非项目特定模式。

阶段类型	Skill取值
数据库schema、迁移、RLS	`postgres-expert`
Server actions、服务、API	`server-action-builder`
带校验的React表单	`react-form-builder`
E2E测试	`playwright-e2e`
React组件/页面	`vercel-react-best-practices`
聚焦UI/UX的工作	`web-design-guidelines`

示例头部信息：

yaml

---
title: "Phase 01 - Database Schema"
skill: postgres-expert
status: pending
group: "auth-system"
dependencies: []
---

分组规则：

构建同一个功能/组件的关联阶段必须使用相同的
```
group:
```
名称
组名需要具备描述性：
```
auth-system
```
、
```
dashboard-ui
```
、
```
data-pipeline
```
单阶段组可用于独立工作
组定义了审计边界——落地过程中一个组的所有阶段完成后，审计人员会统一评审
按依赖从上到下排序组（如果B依赖A，则组A排在组B前面）

涉及多个领域的阶段，填写主skill或使用逗号分隔多个值：

yaml

skill: react-form-builder, vercel-react-best-practices

必填章节（来自模板）：

YAML 头部信息（标题、描述、状态、依赖、标签、日期、skill）
概览（简短描述、单句目标）
上下文与工作流（项目如何使用该模块、用户工作流、解决的问题）
前置条件与澄清（带上下文/假设/影响的用户问题）
需求（功能+技术）
决策日志（阶段专属ADRs）
落地步骤 —— 第0步：优先完成TDD
可验证验收标准（核心路径、质量门禁、集成）
质量保障（手工测试、自动化测试、性能测试、评审清单）
依赖（上游、下游、外部）
完成门禁（签字确认清单）

阶段中的代码块必须匹配步骤4中获取的代码库模式——不要凭记忆编写，不要使用通用示例。通用代码块会导致落地人员编写不符合项目规范的代码，产生返工。如果记不清具体模式，编写代码块前重新读取步骤4中的参考文件。

7c: Validate Phase Quality

7c：校验阶段质量

After creating each phase file, run these validators to catch issues immediately (before review agents get involved):

bash

undefined

创建完每个阶段文件后，运行以下校验工具立即发现问题（在评审Agent介入前）：

bash

undefined

Check for skeleton/placeholder content

echo '{"cwd":"."}' | uv run $CLAUDE_PROJECT_DIR/.claude/hooks/validators/validate_no_placeholders.py
--directory plans/{folder} --extension .md

Check TDD tasks appear before implementation tasks

echo '{"cwd":"."}' | uv run $CLAUDE_PROJECT_DIR/.claude/hooks/validators/validate_tdd_tasks.py
--directory plans/{folder} --extension .md

Confirm the phase file was actually created

echo '{"cwd":"."}' | uv run $CLAUDE_PROJECT_DIR/.claude/hooks/validators/validate_new_file.py
--directory plans/{folder} --extension .md


If any validator exits non-zero, fix the issue before moving to the next phase. Placeholder content and missing TDD steps are the two most common causes of rework during implementation.

echo '{"cwd":"."}' | uv run $CLAUDE_PROJECT_DIR/.claude/hooks/validators/validate_new_file.py
--directory plans/{folder} --extension .md


如果任意校验工具返回非零退出码，先修复问题再进入下一个阶段。占位内容和缺失的TDD步骤是落地阶段返工的两个最常见原因。

7d: Update Task Status

7d：更新任务状态

Mark the phase task as completed, move to next phase.

将当前阶段任务标记为已完成，进入下一个阶段。

7e: Repeat

7e：重复

Continue until all phases are created.

持续执行直到所有阶段创建完成。

Step 8: Checkpoint 2 — Report Completion

步骤8：检查点2 —— 提交完成报告

After all phases are created and validated, send a full summary to the orchestrator:

SendMessage({
  type: "message",
  recipient: "team-lead",
  content: `## Plan Complete — All Phases Created

**Plan folder**: plans/{YYMMDD}-{feature-name}/
**Phases**: {count} phases created

所有阶段创建并校验完成后，向orchestrator提交完整概要：

SendMessage({
  type: "message",
  recipient: "team-lead",
  content: `## Plan Complete — All Phases Created

**Plan folder**: plans/{YYMMDD}-{feature-name}/
**Phases**: {count} phases created

Phase Breakdown

#	Title	Group	Skill	Dependencies	Self-Validation
01	{title}	{group}	{skill}	None	Passed
02	{title}	{group}	{skill}	Phase 01	Passed
...

#	Title	Group	Skill	Dependencies	Self-Validation
01	{title}	{group}	{skill}	None	Passed
02	{title}	{group}	{skill}	Phase 01	Passed
...

Dependency Graph

{describe the dependency flow — which phases unlock which}

Self-Validation Results

Placeholder check: {pass/fail count}
TDD ordering: {pass/fail count}
File creation: {pass/fail count}

Ready for review via /review-plan.`, summary: "All phases created — ready for review" })


Then go idle. The orchestrator will handle spawning review validators and routing feedback.

---

Placeholder check: {pass/fail count}
TDD ordering: {pass/fail count}
File creation: {pass/fail count}

Ready for review via /review-plan.`, summary: "All phases created — ready for review" })


之后进入空闲状态。orchestrator会负责触发评审校验器和流转反馈。

---

Resuming After Context Compact

上下文压缩后恢复流程

If your context was compacted mid-planning:

```
TaskList
```
→ find the
```
in_progress
```
or first
```
pending
```
task
```
TaskGet
```
on that task → read the self-contained description
Continue from that task — don't restart the planning process
The task list is your source of truth, not your memory

Pattern for every work cycle:

TaskList → find in_progress or first pending → TaskGet → continue work → TaskUpdate (completed) → next task

Tasks are the planner's source of truth for progress — not memory, not plan.md alone.

如果规划过程中上下文被压缩：

执行
```
TaskList
```
→ 找到
```
in_progress
```
或第一个
```
pending
```
任务
对该任务执行
```
TaskGet
```
→ 读取独立的任务描述
从该任务继续推进——不要重启整个规划流程
任务列表是进度的唯一可信来源，而非你的记忆

每个工作周期的固定模式：

TaskList → find in_progress or first pending → TaskGet → continue work → TaskUpdate (completed) → next task

任务是规划器进度的可信来源，优先级高于记忆和plan.md本身。

Troubleshooting

故障排查

Context Window Overflow

上下文窗口溢出

Symptom: Planner loses track of phases mid-creation, produces incomplete or inconsistent output.

Cause: Too many phases being created without task tracking, or codebase references consuming too much context.

Fix: Follow Task List pattern in Step 3 — mark tasks complete as you go. For codebase references, read only what you need (one file per type).

症状： 规划器在阶段创建过程中丢失阶段信息，输出不完整或不一致的内容。

原因： 创建阶段时没有跟踪任务，阶段数量过多，或代码库引用占用了过多上下文。

解决方案： 遵循步骤3的任务列表模式——完成任务后及时标记为已完成。代码库引用仅读取必要内容（每类一个文件）。

Missing Template Sections

模板章节缺失

Symptom: Review agents flag missing sections in plan.md or phase files.

Cause: Template not read before writing, or sections skipped during creation.

Fix: Re-read the template (

$CLAUDE_PROJECT_DIR/.claude/skills/create-plan/references/PLAN-TEMPLATE.md

PHASE-TEMPLATE.md

) and add the missing sections. Each section exists because omitting it caused implementation problems.

症状： 评审Agent标记plan.md或阶段文件存在缺失章节。

原因： 编写前未读取模板，或创建过程中跳过了部分章节。

解决方案： 重新读取模板（

$CLAUDE_PROJECT_DIR/.claude/skills/create-plan/references/PLAN-TEMPLATE.md

或

PHASE-TEMPLATE.md

），补充缺失章节。每个章节的存在都是因为之前遗漏该章节导致过落地问题。

Code Blocks Don't Match Codebase

代码块不符合代码库规范

Symptom: Review agents flag code blocks as not matching project patterns.

Cause: Code blocks written from memory instead of from codebase references.

Fix: Re-read the reference file from Step 4 for the relevant file type. Copy the actual pattern — function signatures, imports, naming conventions — into the code block.

症状： 评审Agent标记代码块不符合项目模式。

原因： 代码块凭记忆编写，没有参考代码库引用。

解决方案： 重新读取步骤4中对应文件类型的参考文件，将实际模式（函数签名、导入、命名规范）复制到代码块中。

Orchestrator Not Responding After Checkpoint

检查点提交后orchestrator无响应

Symptom: Sent checkpoint message but no response.

Cause: The orchestrator relays your checkpoint to the user, who may need time to review. This is expected.

Fix: Wait. Do not proceed past a checkpoint without orchestrator approval. The whole point of checkpoints is user course-correction.

症状： 提交了检查点消息但没有收到响应。

原因： orchestrator将你的检查点转发给了用户，用户需要时间评审，属于预期情况。

解决方案： 等待。未获得orchestrator批准前不要越过检查点继续推进。检查点的核心作用就是允许用户修正方向。