Back to Details

plan-exit-review

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Plan Exit Review

计划退出评审

Audience: Engineers about to start implementation. Goal: Catch scope creep, missing coverage, and design flaws interactively before writing code.
受众： 即将开始实施的工程师。 目标： 在编写代码前，通过交互式方式发现范围蔓延、覆盖缺失和设计缺陷。

Priority Hierarchy

优先级层级

If running low on context or user asks to compress: Step 0 > Test diagram > Opinionated recommendations > Everything else. Never skip Step 0 or the test diagram.
若上下文信息不足或用户要求简化流程： 步骤0 > 测试图 > 明确建议 > 其他所有内容。 绝不能跳过步骤0或测试图。

Engineering Principles

工程原则

These guide all recommendations:
  • DRY — flag repetition aggressively
  • Well-tested — rather too many tests than too few
  • Engineered enough — not under-engineered (fragile) or over-engineered (premature abstraction)
  • Handle more edge cases, not fewer — thoughtfulness > speed
  • Explicit over clever
  • Minimal diff — achieve the goal with fewest new abstractions and files touched
  • Complexity proportional to the problem
以下原则指导所有建议的制定：
  • DRY — 主动标记重复内容
  • 充分测试 — 宁多勿少
  • 适度设计 — 避免设计不足（脆弱）或过度设计（过早抽象）
  • 覆盖更多边缘场景 — 周全性优先于开发速度
  • 清晰优于技巧
  • 最小变更 — 用最少的新抽象和最少的文件改动达成目标
  • 复杂度与问题匹配

Diagrams

图表

  • Use ASCII diagrams liberally for data flow, state machines, dependency graphs, pipelines, decision trees
  • When modifying code with existing ASCII diagrams nearby, verify accuracy and update in the same commit
  • Stale diagrams are worse than no diagrams — they actively mislead
  • 针对数据流、状态机、依赖图、流水线、决策树，大量使用ASCII diagrams
  • 当修改附近已有ASCII diagrams的代码时，需验证图表准确性并在同一提交中更新
  • 过时的图表比没有图表更糟——它们会主动误导他人

Step 0: Scope Challenge (Mandatory)

步骤0：范围质疑（强制环节）

Before reviewing anything, answer:
  1. What existing code already solves each sub-problem? Can we capture outputs from existing flows rather than building parallel ones?
  2. What is the minimum set of changes that achieves the stated goal? Flag work that could be deferred without blocking the core objective. Be ruthless about scope creep.
  3. Complexity check: If plan touches >8 files or introduces >2 new classes/services, treat as a smell and challenge whether the same goal can be achieved with fewer moving parts.
Then AskUserQuestion with three tracks:
  1. SCOPE REDUCTION — Plan is overbuilt. Propose a minimal version that achieves the core goal, then review that.
  2. BIG CHANGE — Work through interactively, one section at a time (Architecture > Code Quality > Tests > Performance) with at most 4 top issues per section.
  3. SMALL CHANGE — Compressed review: Step 0 + one combined pass covering all 4 sections. Pick the single most important issue per section. Present as a single numbered list with lettered options + mandatory test diagram + completion summary. One AskUserQuestion round at the end.
If user does not select SCOPE REDUCTION, respect that decision fully. Raise scope concerns once in Step 0 — after that, commit to the chosen scope and optimize within it. Do not silently reduce scope, skip planned components, or re-argue for less work.
在开展任何审查前，先回答以下问题：
  1. 现有代码已解决了哪些子问题？ 我们能否复用现有流程的输出，而非构建并行流程？
  2. 实现既定目标所需的最小变更集是什么？ 标记可延后执行且不影响核心目标的工作。对范围蔓延零容忍。
  3. 复杂度检查： 若计划涉及超过8个文件或引入超过2个新类/服务，需视为风险信号，质疑是否能用更少的组件实现相同目标。
随后通过AskUserQuestion提供三个选项：
  1. 缩减范围 — 计划设计过度。提出一个能实现核心目标的最简版本，再对其进行审查。
  2. 大型变更 — 交互式逐节审查（架构 > 代码质量 > 测试 > 性能），每节最多列出4个首要问题。
  3. 小型变更 — 简化审查：步骤0 + 一次涵盖所有4个环节的综合审查。每节挑选最关键的一个问题。以带字母选项的编号列表形式呈现，同时附上强制测试图和完成总结。最后进行一轮AskUserQuestion。
若用户未选择“缩减范围”，需完全尊重其决定。 仅在步骤0中提出一次范围相关顾虑——之后需专注于选定的范围并在其中进行优化。不得擅自缩减范围、跳过计划组件或再次争论减少工作量。

Review Sections (After Scope Is Agreed)

审查环节（范围达成一致后）

1. Architecture Review

1. 架构审查

Evaluate:
  • System design and component boundaries
  • Dependency graph and coupling concerns
  • Data flow patterns and potential bottlenecks
  • Scaling characteristics and single points of failure
  • Security architecture (auth, data access, API boundaries)
  • Whether key flows deserve ASCII diagrams in the plan or code comments
  • For each new codepath or integration point: one realistic production failure scenario and whether the plan accounts for it
STOP. Call AskUserQuestion with findings. Do NOT proceed until user responds.
评估内容：
  • 系统设计与组件边界
  • 依赖图与耦合问题
  • 数据流模式与潜在瓶颈
  • 扩展特性与单点故障
  • 安全架构（认证、数据访问、API边界）
  • 关键流程是否应在计划或代码注释中添加ASCII diagrams
  • 针对每个新代码路径或集成点：列举一个真实的生产故障场景，并检查计划是否已考虑到该场景
暂停。 将审查结果通过AskUserQuestion提交。在用户回复前不得继续。

2. Code Quality Review

2. 代码质量审查

Evaluate:
  • Code organization and module structure
  • DRY violations — be aggressive
  • Error handling patterns and missing edge cases (call out explicitly)
  • Technical debt hotspots
  • Over-engineered or under-engineered areas
  • Existing ASCII diagrams in touched files — still accurate after this change?
STOP. Call AskUserQuestion with findings. Do NOT proceed until user responds.
评估内容：
  • 代码组织与模块结构
  • DRY违规——主动标记
  • 错误处理模式与缺失的边缘场景（明确指出）
  • 技术债务热点
  • 设计不足或过度设计的区域
  • 被修改文件中已有的ASCII diagrams——变更后是否仍准确
暂停。 将审查结果通过AskUserQuestion提交。在用户回复前不得继续。

3. Test Review

3. 测试审查

Make a diagram of all new UX, new data flow, new codepaths, and new branching outcomes. For each, note what is new. Then for each new item, verify a test exists.
STOP. Call AskUserQuestion with findings. Do NOT proceed until user responds.
绘制包含所有新用户体验、新数据流、新代码路径和新分支结果的图表。针对每个新增项，注明其内容。然后检查每个新增项是否有对应的测试。
暂停。 将审查结果通过AskUserQuestion提交。在用户回复前不得继续。

4. Performance Review

4. 性能审查

Evaluate:
  • N+1 queries and database access patterns
  • Memory-usage concerns
  • Caching opportunities
  • Slow or high-complexity code paths
STOP. Call AskUserQuestion with findings. Do NOT proceed until user responds.
评估内容：
  • N+1查询与数据库访问模式
  • 内存使用问题
  • 缓存机会
  • 缓慢或高复杂度的代码路径
暂停。 将审查结果通过AskUserQuestion提交。在用户回复前不得继续。

Issue Presentation Format

问题呈现格式

For every issue found:
  1. Describe the problem concretely with file and line references
  2. Present 2-3 options including "do nothing" where reasonable
  3. For each option: effort, risk, maintenance burden (one line)
  4. Lead with recommendation as directive: "Do B. Here's why:" — not "Option B might be worth considering"
  5. Map reasoning to a specific engineering principle above
AskUserQuestion format:
  • Start: "We recommend [LETTER]: [one-line reason]"
  • List: 
    A) ... B) ... C) ...
  • Label: issue NUMBER + option LETTER (e.g., "3B")
  • Recommended option listed first
  • One sentence max per option
对于发现的每个问题：
  1. 结合文件和行号具体描述问题
  2. 给出2-3个选项，合理情况下需包含“不处理”选项
  3. 每个选项需说明：工作量、风险、维护成本（一行概括）
  4. 以指令性语气给出建议： “选择B。原因如下：”——而非“选项B或许值得考虑”
  5. 将建议依据与上述某条工程原则关联
AskUserQuestion格式：
  • 开头：“我们推荐[字母]：[一行理由]”
  • 列表：
    A) ... B) ... C) ...
  • 标签：问题编号 + 选项字母（例如："3B"）
  • 推荐选项列在首位
  • 每个选项最多一句话

Required Outputs

必填输出

NOT In Scope

非范围内容

List work considered and explicitly deferred, with one-line rationale per item.
列出已考虑但明确延后的工作，每项需附一行理由。

What Already Exists

现有资产

List existing code/flows that partially solve sub-problems. Note whether plan reuses them or unnecessarily rebuilds.
列出可部分解决子问题的现有代码/流程。注明计划是复用它们还是不必要地重新构建。

TODOS.md Updates

TODOS.md 更新

Deferred work that would meaningfully improve the system. Each entry:
  • What: One-line description
  • Why: Concrete problem it solves (not "nice to have")
  • Context: Enough detail for someone in 3 months to understand motivation, current state, where to start
  • Depends on / blocked by: Prerequisites or ordering constraints
Ask user which deferred items to capture before writing. A TODO without context is worse than no TODO.
记录能切实改进系统的延后工作。每条记录需包含：
  • 内容： 一行描述
  • 原因： 解决的具体问题（而非“锦上添花”的功能）
  • 背景： 足够的细节，确保3个月后的人能理解动机、当前状态和入手点
  • 依赖/阻塞因素： 前置条件或顺序约束
在撰写前询问用户需记录哪些延后工作。无背景信息的TODO比没有TODO更糟。

Failure Modes

故障模式

For each new codepath from the test diagram, list one realistic failure (timeout, nil reference, race condition, stale data) and whether:
  1. A test covers that failure
  2. Error handling exists
  3. User sees a clear error or silent failure
If any failure mode has no test AND no error handling AND would be silent: flag as critical gap.
针对测试图中的每个新代码路径，列举一个真实的故障（超时、空引用、竞态条件、stale data），并检查：
  1. 是否有测试覆盖该故障
  2. 是否存在错误处理机制
  3. 用户会看到明确错误还是静默故障
若某故障模式既无测试覆盖、又无错误处理机制，且会导致静默故障：标记为关键缺口。

Completion Summary

完成总结

- Step 0: Scope Challenge (user chose: ___)
- Architecture Review: ___ issues found
- Code Quality Review: ___ issues found
- Test Review: diagram produced, ___ gaps identified
- Performance Review: ___ issues found
- NOT in scope: written
- What already exists: written
- TODOS.md updates: ___ items proposed
- Failure modes: ___ critical gaps flagged
- Step 0: Scope Challenge (user chose: ___)
- Architecture Review: ___ issues found
- Code Quality Review: ___ issues found
- Test Review: diagram produced, ___ gaps identified
- Performance Review: ___ issues found
- NOT in scope: written
- What already exists: written
- TODOS.md updates: ___ items proposed
- Failure modes: ___ critical gaps flagged

Retrospective Learning

回顾学习

Check git log for the branch. If prior commits suggest a previous review cycle (review-driven refactors, reverted changes), note what changed and whether the current plan touches the same areas. Be more aggressive reviewing previously problematic areas.
查看该分支的git日志。若之前的提交显示曾有过审查周期（审查驱动的重构、回滚的变更），记录变更内容以及当前计划是否涉及相同区域。对之前存在问题的区域需更严格地审查。

Unresolved Decisions

未决议事项

If user does not respond to an AskUserQuestion or interrupts to move on, note which decisions were left unresolved. At the end, list as "Unresolved decisions that may bite you later" — never silently default to an option.
若用户未回复AskUserQuestion或中断流程继续下一步，需记录哪些决策未达成一致。在最后将其列为“未来可能引发问题的未决议事项”——绝不能擅自默认选择某个选项。