plan

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Plan

Investigate the codebase, design the change, and write

.handoff/plan.md

. No code modification, no command execution.

调查代码库、设计变更方案并编写

.handoff/plan.md

。不修改代码，不执行命令。

Gate (run first)

准入检查（优先执行）

Read
```
.handoff/config.md
```
. If missing, abort:
❌ No config found. Run
```
/setup-handoff
```
first.

Re-entry check. Inspect

.handoff/

for retained state:

State	Mode	Action
`plan.md` AND `review.md` exist	Blocked cycle	Read both. The previous plan attempted work; review.md lists blockers. The new plan must address the blockers. Preserve the existing structure: keep `## Background` , keep `## Phases` (if any) including the current `[🔄]` marker — verify did not advance because blocking retains state and this phase's work isn't done. Replace only the parts that review.md identifies as broken. If previous plan had `> Addresses backlog: ...` , carry the marker forward (🔄 items in backlog stay 🔄).
`plan.md` exists with `## Phases` and a `[🔄]` marker, `review.md` absent	Phase advance	Read previous plan to inherit context. Inherit `## Background` and `## Phases` (with markers already advanced by verify). Replace the previous phase's `## Change list` , `## Sync commands` , `## Test strategy` , `## Verification plan` , and `## Compile check` (if any) with the new `[🔄]` phase's content. Carry forward `> Addresses backlog: ...` if present.
`plan.md` exists, no Phases section, `review.md` absent	Unusual	Verify normally cleans up after pass. This state suggests manual edit. Ask the user: "Found retained plan.md without phases or review. Continue editing it, or start fresh?"
None exist	Fresh plan	Proceed normally.

If
```
.handoff/backlog.md
```
exists and has any open items: see backlog-handling.md.

读取
```
.handoff/config.md
```
。若文件缺失则终止操作：
❌ 未找到配置文件，请先运行
```
/setup-handoff
```
。

重入状态检查。检查

.handoff/

目录中的保留状态：

状态	模式	操作
`plan.md` 和 `review.md` 均存在	阻塞周期	读取两个文件。之前的计划已尝试开展工作；review.md列出了阻塞点。新计划必须解决这些阻塞点。保留现有结构：保留 `## Background` （背景）、保留 `## Phases` （阶段，若存在）包括当前的 `[🔄]` 标记——由于阻塞状态未清除，该阶段工作未完成，因此verify未推进阶段。仅替换review.md指出有问题的部分。若之前的计划包含 `> Addresses backlog: ...` （处理待办事项：...），则保留该标记（待办事项中的🔄项保持🔄状态）。
存在带 `## Phases` 和 `[🔄]` 标记的 `plan.md` ，无 `review.md`	阶段推进	读取之前的计划以继承上下文。继承 `## Background` 和 `## Phases` （标记已由verify推进）。将前一阶段的 `## Change list` （变更列表）、 `## Sync commands` （同步命令）、 `## Test strategy` （测试策略）、 `## Verification plan` （验证计划）和 `## Compile check` （编译检查，若存在）替换为当前 `[🔄]` 阶段的内容。若存在 `> Addresses backlog: ...` 则保留。
存在 `plan.md` ，无Phases章节，无 `review.md`	异常状态	正常情况下verify会在完成后清理状态。此状态表明存在手动编辑。询问用户："发现保留的plan.md无阶段或审查内容。是继续编辑该文件，还是重新开始？"
无上述文件	全新计划	正常推进。

若
```
.handoff/backlog.md
```
存在且包含未处理项：请查看backlog-handling.md。

Output language

输出语言

All output from this skill — conversational replies to the user, status/progress messages, AND the written

plan.md

— uses the language specified by

config.md

response_language

. Default if config missing or field absent:

en

. Code, file paths, command syntax, and identifiers stay in their native language regardless.

本技能的所有输出——对用户的对话回复、状态/进度消息，以及生成的

plan.md

——均使用

config.md

中

response_language

指定的语言。若配置文件缺失或该字段未设置，默认使用

en

（英语）。代码、文件路径、命令语法和标识符无论如何均保留其原始语言。

Workflow

工作流程

Determine task scope based on Gate's matched re-entry mode:
- Fresh plan: resolve task description from
```
/plan "<arg>"
```
  if provided; otherwise the user typed
```
/plan
```
  alone and we may need to surface the backlog (see backlog-handling.md).
- Blocked cycle: task is "address the blockers from review.md". Do NOT redesign Background or Phases — preserve them. Only revise
```
## Change list
```
  (and dependent sections like
```
## Sync commands
```
  ,
```
## Verification plan
```
  ) where review.md says they were wrong.
- Phase advance: task is "design the
```
[🔄]
```
  phase's change list". Inherit
```
## Background
```
  and
```
## Phases
```
  from the previous plan.md as-is. Skip step 3 (scope assessment — phases are already declared).
- Unusual: stop and ask user (per Gate's instruction).
Investigate the codebase. Use the convention docs path and project doc index from config to guide what to read. Look at existing patterns the change must match.
Assess scope (skip if Gate matched Blocked cycle or Phase advance — scope was already decided in the original plan). If the work has clear, sequentially-dependent stages that are each independently verifiable (e.g., DB migration → API → frontend → cleanup), propose splitting into
```
## Phases
```
. Confirm with user before committing to a multi-phase plan. Otherwise proceed as a single-cycle plan.
Design the change list. Match the structure described in plan-template.md: change list, sync commands (if any), test strategy, verification plan.
- Verification scope decision. When filling the
```
## Verification plan
```
  section, look at the change list and pick ONLY the commands that actually apply.
```
/verify
```
  will run exactly what's listed there. Typecheck is /execute's job — typically don't list it under verification. If the change is docs-only (or otherwise needs no command verification), write
```
(none — <one-line rationale>)
```
  .
- Compile check opt-out. If the change should NOT trigger /execute's compile check (e.g., docs-only, intentional WIP), add a
```
## Compile check
```
  section with body
```
(none — <rationale>)
```
  . Otherwise omit the section entirely (default = run config's typecheck).

Risk-tag the change list. For each change list item, decide whether to escalate:

Signal	Suggested tag
Path: `migrations/` , `auth/` , `infra/` , `.config.` , `.github/workflows/` , security-sensitive areas	medium-high
Operations: delete / drop / alter / rotate / rename	medium-high
Public API or cross-package signature change (callers in other packages)	medium
> 5 files touched in one item, or > 20 in the plan	medium
Side effects: DB schema, fs writes, network calls, auth changes, concurrency primitives	medium-high
Plain logic edit, single file, no signature change	low / untagged

Default to leaving items untagged (= low). Suggest escalations to the user; require a one-line reason for any

high

. Do NOT inflate tags "just to be safe" — every

high

slows execute and surfaces in review.

Non-interactive flows: when no user input channel is available (scripted invocation, headless agent, CI), default all items to untagged (low) and skip the suggestion step. Do NOT auto-assign

medium

high

without confirmation — auto-tagging would either over-cautiously slow every execute or under-tag missed signals. Keep the safe default and let an interactive re-run upgrade tags when warranted.

Identify independent units. Look at the change list: are there subsets of files/changes that can be applied independently (no shared types, no shared sync command, no sequential dependency)? If yes, list them as parallelizable groups in plan.md's optional
```
## Parallelization
```
section. If everything is sequential or tightly coupled, omit the section.
Do NOT include
high
-risk items in parallelizable groups. Parallel dispatch (handled by /execute) skips per-item compile checks — only the final safety-net check runs.
```
high
```
items are tagged precisely because they need per-item discipline; putting them in a parallel group silently strips that safety. Either keep high items sequential (omit them from
```
## Parallelization
```
) or — if parallel execution truly outweighs per-item check — downgrade them to medium with a one-line justification.
Write
```
.handoff/plan.md
```
.
If backlog items are being addressed, also mark them 🔄 in
```
.handoff/backlog.md
```
(see backlog-handling.md §3). For multi-phase plans, the marker stays 🔄 across all phases until the final phase passes verify.

Print:

✅ Plan written to .handoff/plan.md
<if multi-phase:> Active phase: [N] <title>
Next step: /execute (recommended in a fresh chat to keep context clean)

根据准入检查匹配的重入模式确定任务范围：
- 全新计划：若提供了
```
/plan "<arg>"
```
  ，则从中解析任务描述；否则用户仅输入了
```
/plan
```
  ，可能需要展示待办事项（详见backlog-handling.md）。
- 阻塞周期：任务为"解决review.md中的阻塞点"。不要重新设计Background或Phases——保留现有内容。仅在review.md指出有误的地方修改
```
## Change list
```
  （及相关章节如
```
## Sync commands
```
  、
```
## Verification plan
```
  ）。
- 阶段推进：任务为"设计
```
[🔄]
```
  阶段的变更列表"。原样继承之前plan.md中的
```
## Background
```
  和
```
## Phases
```
  。跳过步骤3（范围评估——阶段已在原始计划中定义）。
- 异常状态：停止并询问用户（按照准入检查的指示）。
调查代码库。使用配置文件中的约定文档路径和项目文档索引指导阅读内容。查看变更必须匹配的现有模式。
评估范围（若准入检查匹配阻塞周期或阶段推进则跳过——范围已在原始计划中确定）。若工作包含清晰的、可独立验证的顺序依赖阶段（例如：数据库迁移→API→前端→清理），建议拆分为
```
## Phases
```
（多阶段）。在确定多阶段计划前需与用户确认。否则按单周期计划推进。
设计变更列表。匹配plan-template.md中描述的结构：变更列表、同步命令（若有）、测试策略、验证计划。
- 验证范围决策。填写
```
## Verification plan
```
  章节时，查看变更列表并仅选择实际适用的命令。
```
/verify
```
  将严格执行列表中的命令。类型检查是/execute的工作——通常不要在验证部分列出。若变更仅涉及文档（或无需命令验证），则填写
```
(none — <单行理由>)
```
  。
- 编译检查豁免。若变更不应触发/execute的编译检查（例如：仅修改文档、故意的WIP），添加
```
## Compile check
```
  章节并填写
```
(none — <理由>)
```
  。否则完全省略该章节（默认 = 运行配置中的类型检查）。

为变更列表添加风险标记。对每个变更列表项，决定是否升级风险等级：

信号	建议标记
路径： `migrations/` 、 `auth/` 、 `infra/` 、 `.config.` 、 `.github/workflows/` 、安全敏感区域	medium-high（中高）
操作：删除/丢弃/修改/轮换/重命名	medium-high（中高）
公共API或跨包签名变更（其他包中有调用者）	medium（中）
单个项涉及超过5个文件，或整个计划涉及超过20个文件	medium（中）
副作用：数据库 schema、文件系统写入、网络调用、认证变更、并发原语	medium-high（中高）
普通逻辑编辑、单个文件、无签名变更	low / 无标记（低）

默认不标记（=低风险）。向用户建议升级风险等级；若标记为

high

（高），需提供单行理由。不要为了"安全起见"随意提高标记等级——每个

high

标记都会减慢execute的速度，并在审查中突出显示。

非交互流程：当无用户输入渠道时（脚本调用、无头Agent、CI），默认所有项无标记（低风险）并跳过建议步骤。不要自动分配
medium
或
high
标记——自动标记要么过于谨慎地减慢每个execute的速度，要么遗漏信号导致标记不足。保持安全默认值，在需要时通过交互式重新运行升级标记。

识别独立单元。查看变更列表：是否存在可独立应用的文件/变更子集（无共享类型、无共享同步命令、无顺序依赖）？若是，在plan.md的可选
```
## Parallelization
```
（并行化）章节中将其列为可并行组。若所有内容均为顺序执行或紧密耦合，则省略该章节。
不要将
high
风险项纳入可并行组。并行调度（由/execute处理）会跳过每项的编译检查——仅运行最终的安全检查。
```
high
```
项被标记正是因为它们需要逐项检查；将其放入并行组会悄无声息地移除该安全保障。要么保持高风险项按顺序执行（不纳入
```
## Parallelization
```
），要么——如果并行执行的好处确实超过逐项检查的必要性——将其降级为medium并提供单行理由。
编写
```
.handoff/plan.md
```
。
若正在处理待办事项，需在
```
.handoff/backlog.md
```
中标记为🔄（详见backlog-handling.md §3）。对于多阶段计划，该标记在所有阶段中保持🔄，直到最后一个阶段通过verify。

打印：

✅ 计划已写入 .handoff/plan.md
<若为多阶段：> 当前阶段：[N] <标题>
下一步：/execute（建议在新对话中运行以保持上下文清晰）

Boundaries

边界限制

Allowed: read any file, web search, write
```
.handoff/plan.md
```
, mark items in
```
.handoff/backlog.md
```
.
Forbidden: modify code, run build/test/lint commands, create or delete project files.

允许操作：读取任意文件、网页搜索、写入
```
.handoff/plan.md
```
、标记
```
.handoff/backlog.md
```
中的项。
禁止操作：修改代码、运行构建/测试/ lint命令、创建或删除项目文件。