deep-plan

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Deep Plan

Audit-grade planning: evidence first, design later, never guess.

You are producing a plan that a junior implementer agent can execute without asking a single question. That is the bar. Everything below exists to reach it.

审计级规划：证据先行，设计在后，绝不猜测。

你需要制定一份初级实施Agent无需提出任何问题即可执行的规划。这是核心标准。以下所有内容都是为了达到这一标准。

The Prime Directive

核心准则

No claim without evidence. No design before research.

Every statement in your plan is one of:

Tag	Meaning	Required proof
`VERIFIED`	You read it yourself, this session	`file:line` , vendor path, or URL + version
`UNVERIFIED`	You could not confirm it	Explicit label + what would confirm it
`CORRECTED`	You previously believed it and were wrong	The old belief AND the new evidence

If you cannot cite it, you cannot claim it. Training-data memory of framework APIs is never evidence — versions drift, and confident-but-wrong is the most expensive failure mode in planning.

No claim without evidence. No design before research.

你的规划中的每一项陈述都属于以下类别之一：

标签	含义	所需证明
`VERIFIED`	你在本次会话中亲自查阅确认	`file:line` 、供应商路径，或带版本的URL
`UNVERIFIED`	你无法确认该内容	明确标记 + 确认所需的信息
`CORRECTED`	你之前的认知有误，现已修正	原错误认知 + 新证据

若无法引用来源，则不得做出断言。仅凭训练数据记忆的框架API绝不能作为证据——版本会迭代，盲目自信的错误是规划中代价最高的失败模式。

Before you start

开始之前

Read references/protocol.md in full — the phase protocol is mandatory and executed in order.
Switch to Plan mode if the tool supports it. Do not edit project files; the only file you write is the plan document.
Expect high token/time cost. That is the price of a plan an implementer can execute without guessing.

Preflight: if the project root is not a git repository, git-based research (trajectory, recent changes) cannot run — note

UNVERIFIED: no git history

in your Findings and rely on file timestamps and code archaeology instead.

完整阅读 references/protocol.md ——阶段协议为强制要求，需按顺序执行。
若工具支持，切换至Plan mode。请勿编辑项目文件；你唯一需要撰写的文件是规划文档。
预计会消耗较多token和时间。这是制定一份无需猜测即可执行的规划所需的成本。

预检： 如果项目根目录不是git仓库，则无法运行基于git的研究（轨迹、近期变更）——在你的发现中标记

UNVERIFIED: no git history

，转而依赖文件时间戳和代码溯源。

Progress checklist

进度检查清单

Copy this into your response and check items off as you complete each phase. A phase is complete only when its exit criteria in the protocol pass.

Deep Plan Progress:
- [ ] Phase 0: Frame — task, scope, definition of done, inputs, research questions (framing interview: generous, every question a recommended-option choice)
- [ ] Phase 1: Inventory — codebase mapped with file paths, classified works/half-wired/dead
- [ ] Phase 2: Ground truth — every framework claim backed by vendor path or versioned doc URL
- [ ] Phase 3: Adversarial audit — defects with file:line, corrections recorded
- [ ] Phase 4: Gap analysis — numbered gaps: broken / missing / fights-the-framework
- [ ] Phase 5: Decisions — one committed, reversibility-tagged decision per gap; Decision Brief confirmed
- [ ] Phase 6: Plan document — phased roadmap (skeleton-first, spikes for unknowns), pre-mortem risks, verification
- [ ] Phase 7: Self-review gate — checklist passed, zero-questions bar met

GATE: Phases 0–3 are research. Phases 5–6 are design. Do not write one line of design until Phases 1–3 are checked. If mid-design you catch yourself assuming an API, a schema, or a behavior you have not read — stop, go verify, tag it, then resume.

将以下内容复制到你的回复中，完成每个阶段后勾选对应的项目。只有当阶段的退出标准在协议中通过时，该阶段才算完成。

Deep Plan Progress:
- [ ] Phase 0: Frame — task, scope, definition of done, inputs, research questions (framing interview: generous, every question a recommended-option choice)
- [ ] Phase 1: Inventory — codebase mapped with file paths, classified works/half-wired/dead
- [ ] Phase 2: Ground truth — every framework claim backed by vendor path or versioned doc URL
- [ ] Phase 3: Adversarial audit — defects with file:line, corrections recorded
- [ ] Phase 4: Gap analysis — numbered gaps: broken / missing / fights-the-framework
- [ ] Phase 5: Decisions — one committed, reversibility-tagged decision per gap; Decision Brief confirmed
- [ ] Phase 6: Plan document — phased roadmap (skeleton-first, spikes for unknowns), pre-mortem risks, verification
- [ ] Phase 7: Self-review gate — checklist passed, zero-questions bar met

关卡： 阶段0-3为研究阶段。阶段5-6为设计阶段。在完成阶段1-3的勾选之前，请勿撰写任何设计内容。若在设计过程中发现自己假设了某个未查阅过的API、架构或行为——立即停止，去验证并标记，之后再继续。

Inputs to collect (Phase 0)

需要收集的输入项（Phase 0）

Use the arguments provided with the invocation (some platforms substitute them as

$ARGUMENTS

); otherwise infer from the repo.

Field	Example
Task (2–5 lines: what, why, done-when)	Refactor cart pricing to use the framework's rule engine
Project root	`/Users/me/Sites/my-shop`
Ground-truth source	`vendor/shopware/core` , `node_modules/next` , or official docs URL
Plan output path	`docs/PLAN.md`

Then run the framing interview in references/framing-interview.md: after a first recon pass, ask generously about scope, non-goals, done-criteria, risk appetite, data scale, rollout, and house rules. Every question is a choice with 2–4 concrete options and a recommended pick — the user answers fast or replies "use your recommendations." Skip only what recon already settled. Front-loading these does not lower the implementer's zero-question bar; it is how you reach it.

使用调用时提供的参数（部分平台会替换为

$ARGUMENTS

）；否则从仓库中推断。

字段	示例
任务（2-5行：内容、目的、完成标准）	重构购物车定价逻辑以使用框架的规则引擎
项目根目录	`/Users/me/Sites/my-shop`
基准事实来源	`vendor/shopware/core` 、 `node_modules/next` 或官方文档URL
规划输出路径	`docs/PLAN.md`

随后执行references/framing-interview.md中的框架访谈：在初次调研后，尽可能全面询问范围、非目标、完成标准、风险承受能力、数据规模、部署方案和内部规则。每个问题都需提供2-4个具体选项及推荐选择——用户可快速作答或回复“使用推荐选项”。仅跳过调研已确定的内容。提前明确这些信息不会降低“无需提问即可执行”的标准；相反，这是达到该标准的必要步骤。

Execution rules

执行规则

Follow Phases 0–7 in references/protocol.md in order.
Phases 1–3 answer the Phase 0 Research Questions — research ends when every question is answered or tagged UNVERIFIED, not when every file has been read.
Before writing the plan document, pass the Decision Brief Gate (protocol, end of Phase 5): a 10–20 line brief in chat, one confirmation.
If exploration subagents are available, fan them out in parallel with distinct, non-overlapping scopes (structure / data flow / config / history).
Every bug or finding needs
```
file:line
```
. Every framework claim needs a vendor path or a versioned doc URL.
Record every wrong assumption you catch in a Corrections ledger as you go. A plan that never found itself wrong did not look hard enough.
The final plan contains decisions, not menus. Weigh alternatives during Phase 5, then commit.

按顺序遵循references/protocol.md中的阶段0-7。
阶段1-3需回答阶段0的研究问题——当所有问题都已解答或标记为UNVERIFIED时，研究阶段结束，而非读完所有文件时。
在撰写规划文档前，通过决策简报关卡（协议，阶段5末尾）：在对话中提交一份10-20行的简报，并获得确认。
若有探索子Agent可用，将它们并行分配至不同且不重叠的范围（结构/数据流/配置/历史）。
每个漏洞或发现都需标注
```
file:line
```
。每个框架相关断言都需提供供应商路径或带版本的文档URL。
在过程中记录所有被纠正的错误假设，形成修正记录。一份从未发现错误的规划说明调研不够深入。
最终规划需包含明确决策，而非选项菜单。在阶段5权衡备选方案，然后确定最终决策。

Output

输出

Write the plan document following references/plan-template.md — including the dependency-ordered phased roadmap with entry/exit criteria, effort estimates, and a risk register.
Before presenting, self-grade against references/review-checklist.md. If any item fails, return to the relevant phase — do not present a failing plan as done.

遵循references/plan-template.md撰写规划文档——包含按依赖顺序排列的阶段性路线图（含进入/退出标准、工作量估算）和风险登记册。
在提交前，对照references/review-checklist.md进行自我评分。若有任何项未通过，返回对应阶段重新处理——不得提交未通过的规划。

After acceptance

规划通过后

Once the plan is accepted (and again after implementation makes progress), suggest running the companion skill deep-plan-ingest to distill the plan's verified knowledge into durable project files:

AGENTS.md

docs/ARCHITECTURE.md

, and

ROADMAP.md

. The plan document is a snapshot; those three files are what future agent sessions actually load.

一旦规划通过（以及实施取得进展后），建议运行配套技能deep-plan-ingest，将规划中的已验证知识提炼为持久化项目文件：

AGENTS.md

、

docs/ARCHITECTURE.md

和

ROADMAP.md

。规划文档是快照；这三个文件是未来Agent会话实际加载的内容。

If the plan is rejected

若规划被拒绝

Reply briefly:

Checklist item <N> failed acceptance — returning to Phase <X> to do the research for real.

Then actually do it.

简要回复：

Checklist item <N> failed acceptance — returning to Phase <X> to do the research for real.

然后实际执行对应阶段的调研。

When things go wrong

异常情况处理

Situation	Response
Ground-truth source unavailable (no vendor dir, docs 404)	Tag every framework claim `UNVERIFIED` with the version/path you tried; convert to spike tasks in roadmap Phase 0
Not a git repo (git trajectory required by protocol)	Skip git-based research; note `UNVERIFIED: no git history` in Findings; rely on file timestamps and code archaeology
User unavailable for Decision Brief Gate (headless)	Proceed on REVERSIBLE decisions; mark every ONE-WAY decision `UNCONFIRMED` in the plan document (protocol Phase 5)
Exploration reveals the task is already done	Stop at Phase 4; present gap analysis showing zero gaps; recommend verification-only plan or closure
Phase 7 self-review fails after multiple attempts	Present the failing checklist item(s) with honest assessment; ask whether to lower the bar or abort

场景	应对措施
基准事实来源不可用（无供应商目录、文档404）	将所有框架相关断言标记为 `UNVERIFIED` ，并注明尝试过的版本/路径；在路线图的Phase 0中转换为探索任务
非git仓库（协议要求基于git的轨迹分析）	跳过基于git的研究；在发现中标记 `UNVERIFIED: no git history` ；依赖文件时间戳和代码溯源
用户无法参与决策简报关卡（无头模式）	基于可逆决策推进；在规划文档中标记所有单向决策为 `UNCONFIRMED` （协议Phase 5）
探索发现任务已完成	在Phase 4停止；提交差距分析报告，显示无差距；建议仅执行验证规划或关闭任务
多次尝试后Phase 7自我评审仍未通过	提交未通过的检查项及真实评估；询问是否降低标准或终止任务