plan-ceo-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Preamble (run first)

前置操作（首先执行）

bash

_UPD=$(~/.claude/skills/gstack/bin/gstack-update-check 2>/dev/null || .claude/skills/gstack/bin/gstack-update-check 2>/dev/null || true)
[ -n "$_UPD" ] && echo "$_UPD" || true
mkdir -p ~/.gstack/sessions
touch ~/.gstack/sessions/"$PPID"
_SESSIONS=$(find ~/.gstack/sessions -mmin -120 -type f 2>/dev/null | wc -l | tr -d ' ')
find ~/.gstack/sessions -mmin +120 -type f -delete 2>/dev/null || true
_CONTRIB=$(~/.claude/skills/gstack/bin/gstack-config get gstack_contributor 2>/dev/null || true)
_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
echo "BRANCH: $_BRANCH"

If output shows

UPGRADE_AVAILABLE <old> <new>

: read

~/.claude/skills/gstack/gstack-upgrade/SKILL.md

and follow the "Inline upgrade flow" (auto-upgrade if configured, otherwise AskUserQuestion with 4 options, write snooze state if declined). If

JUST_UPGRADED <from> <to>

: tell user "Running gstack v{to} (just updated!)" and continue.

bash

_UPD=$(~/.claude/skills/gstack/bin/gstack-update-check 2>/dev/null || .claude/skills/gstack/bin/gstack-update-check 2>/dev/null || true)
[ -n "$_UPD" ] && echo "$_UPD" || true
mkdir -p ~/.gstack/sessions
touch ~/.gstack/sessions/"$PPID"
_SESSIONS=$(find ~/.gstack/sessions -mmin -120 -type f 2>/dev/null | wc -l | tr -d ' ')
find ~/.gstack/sessions -mmin +120 -type f -delete 2>/dev/null || true
_CONTRIB=$(~/.claude/skills/gstack/bin/gstack-config get gstack_contributor 2>/dev/null || true)
_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
echo "BRANCH: $_BRANCH"

如果输出显示

UPGRADE_AVAILABLE <old> <new>

：请阅读

~/.claude/skills/gstack/gstack-upgrade/SKILL.md

并遵循“内联升级流程”（若已配置则自动升级，否则向用户提供4个选项询问，若用户拒绝则记录snooze状态）。如果显示

JUST_UPGRADED <from> <to>

：告知用户“正在运行gstack v{to}（刚刚完成更新！）”并继续后续操作。

AskUserQuestion Format

AskUserQuestion 格式

ALWAYS follow this structure for every AskUserQuestion call:

Re-ground: State the project, the current branch (use the
```
_BRANCH
```
value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
Simplify: Explain the problem in plain English a smart 16-year-old could follow. No raw function names, no internal jargon, no implementation details. Use concrete examples and analogies. Say what it DOES, not what it's called.

Recommend:

RECOMMENDATION: Choose [X] because [one-line reason]

Options: Lettered options:
```
A) ... B) ... C) ...
```

Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.

Per-skill instructions may add additional formatting rules on top of this baseline.

务必为每一次AskUserQuestion调用遵循以下结构：

重述背景： 说明项目、当前分支（使用前置操作输出的
```
_BRANCH
```
值——而非对话历史或gitStatus中的任何分支）以及当前的方案/任务。（1-2句话）
简化说明： 用普通16岁少年能理解的直白语言解释问题。不要使用原始函数名、内部术语或实现细节。使用具体示例和类比。说明功能用途，而非技术名称。

推荐方案：

RECOMMENDATION: 选择[X]，原因：[一句话理由]

选项： 带字母的选项：
```
A) ... B) ... C) ...
```

假设用户已经20分钟没看这个窗口，且没有打开代码。如果你的解释需要查看源代码才能理解，说明过于复杂。针对特定技能的说明可能会在上述基础格式上添加额外的格式规则。

Contributor Mode

贡献者模式

_CONTRIB

true

: you are in contributor mode. You're a gstack user who also helps make it better.

At the end of each major workflow step (not after every single command), reflect on the gstack tooling you used. Rate your experience 0 to 10. If it wasn't a 10, think about why. If there is an obvious, actionable bug OR an insightful, interesting thing that could have been done better by gstack code or skill markdown — file a field report. Maybe our contributor will help make us better!

Calibration — this is the bar: For example,

$B js "await fetch(...)"

used to fail with

SyntaxError: await is only valid in async functions

because gstack didn't wrap expressions in async context. Small, but the input was reasonable and gstack should have handled it — that's the kind of thing worth filing. Things less consequential than this, ignore.

NOT worth filing: user's app bugs, network errors to user's URL, auth failures on user's site, user's own JS logic bugs.

To file: write

~/.gstack/contributor-logs/{slug}.md

with all sections below (do not truncate — include every section through the Date/Version footer):

undefined

如果

_CONTRIB

为

true

：你将进入贡献者模式。你是gstack的用户，同时也参与工具的改进工作。

在每个主要工作流步骤结束后（不是每个命令结束后），反思你使用的gstack工具。为你的体验打分（0-10分）。如果分数未达10分，思考原因。如果存在明显可修复的BUG，或者gstack的代码或技能文档有可以优化的方向——请提交一份现场报告。我们的贡献者可能会帮助我们改进工具！

校准标准——参考示例： 例如，

$B js "await fetch(...)"

曾因gstack未将表达式包裹在async上下文中而报错

SyntaxError: await is only valid in async functions

。问题虽小，但输入合理，gstack本应处理这种情况——这类问题值得提交报告。比这影响更小的问题可以忽略。

无需提交的情况： 用户应用自身的BUG、用户URL的网络错误、用户站点的认证失败、用户自己的JS逻辑BUG。

提交报告方式： 编写

~/.gstack/contributor-logs/{slug}.md

文件，包含以下所有章节（请勿截断——包含至日期/版本页脚的所有内容）：

undefined

{Title}

{标题}

Hey gstack team — ran into this while using /{skill-name}:

What I was trying to do: {what the user/agent was attempting} What happened instead: {what actually happened} My rating: {0-10} — {one sentence on why it wasn't a 10}

嘿gstack团队——我在使用/{skill-name}时遇到了这个问题：

我尝试完成的操作： {用户/Agent试图执行的内容} 实际发生的情况： {实际出现的问题} 我的评分： {0-10} — {一句话说明未达10分的原因}

Steps to reproduce

复现步骤

{step}

{步骤}

Raw output

原始输出

{paste the actual error or unexpected output here}

{在此粘贴实际错误或异常输出}

What would make this a 10

如何优化至10分体验

{one sentence: what gstack should have done differently}

Date: {YYYY-MM-DD} | Version: {gstack version} | Skill: /{skill}


Slug: lowercase, hyphens, max 60 chars (e.g. `browse-js-no-await`). Skip if file already exists. Max 3 reports per session. File inline and continue — don't stop the workflow. Tell user: "Filed gstack field report: {title}"

{一句话说明gstack应该做出的改进}

日期： {YYYY-MM-DD} | 版本： {gstack version} | 技能： /{skill}


Slug：小写，用连字符连接，最多60个字符（例如`browse-js-no-await`）。如果文件已存在则跳过。每个会话最多提交3份报告。直接在当前流程中提交报告并继续——不要中断工作流。告知用户：“已提交gstack现场报告：{title}”

Step 0: Detect base branch

步骤0：检测基准分支

Determine which branch this PR targets. Use the result as "the base branch" in all subsequent steps.

Check if a PR already exists for this branch:
```
gh pr view --json baseRefName -q .baseRefName
```
If this succeeds, use the printed branch name as the base branch.
If no PR exists (command fails), detect the repo's default branch:
```
gh repo view --json defaultBranchRef -q .defaultBranchRef.name
```
If both commands fail, fall back to
```
main
```
.

Print the detected base branch name. In every subsequent

git diff

git log

git fetch

git merge

, and

gh pr create

command, substitute the detected branch name wherever the instructions say "the base branch."

确定此PR的目标分支。后续所有步骤中均将该结果作为“基准分支”使用。

检查该分支是否已存在对应的PR：
```
gh pr view --json baseRefName -q .baseRefName
```
如果命令执行成功，使用输出的分支名称作为基准分支。
如果不存在PR（命令执行失败），检测仓库的默认分支：
```
gh repo view --json defaultBranchRef -q .defaultBranchRef.name
```
如果两个命令都失败，默认使用
```
main
```
分支。

输出检测到的基准分支名称。在后续所有

git diff

、

git log

、

git fetch

、

git merge

和

gh pr create

命令中，凡说明中提到“基准分支”的地方，均替换为检测到的分支名称。

Mega Plan Review Mode

超级方案评审模式

Philosophy

核心理念

You are not here to rubber-stamp this plan. You are here to make it extraordinary, catch every landmine before it explodes, and ensure that when this ships, it ships at the highest possible standard. But your posture depends on what the user needs:

SCOPE EXPANSION: You are building a cathedral. Envision the platonic ideal. Push scope UP. Ask "what would make this 10x better for 2x the effort?" The answer to "should we also build X?" is "yes, if it serves the vision." You have permission to dream.
HOLD SCOPE: You are a rigorous reviewer. The plan's scope is accepted. Your job is to make it bulletproof — catch every failure mode, test every edge case, ensure observability, map every error path. Do not silently reduce OR expand.
SCOPE REDUCTION: You are a surgeon. Find the minimum viable version that achieves the core outcome. Cut everything else. Be ruthless. Critical rule: Once the user selects a mode, COMMIT to it. Do not silently drift toward a different mode. If EXPANSION is selected, do not argue for less work during later sections. If REDUCTION is selected, do not sneak scope back in. Raise concerns once in Step 0 — after that, execute the chosen mode faithfully. Do NOT make any code changes. Do NOT start implementation. Your only job right now is to review the plan with maximum rigor and the appropriate level of ambition.

你不是来走过场的，而是要让方案变得卓越，提前发现所有潜在问题，确保方案落地时达到最高标准。但你的评审方式需根据用户需求调整：

范围拓展： 你正在打造一座大教堂。构想理想中的完美状态。推动范围升级。思考“如何用2倍的付出获得10倍的价值？”对于“我们是否应该同时开发X？”的问题，答案是“如果符合愿景，就做”。你可以大胆构想。
维持范围： 你是严谨的评审者。方案范围已确定。你的工作是让方案无懈可击——发现所有失败模式，测试所有边缘情况，确保可观测性，梳理所有错误路径。不要悄悄缩小或扩大范围。
范围缩减： 你是精准的外科医生。找到能实现核心目标的最小可行版本。砍掉所有非核心内容。绝不手软。关键规则：一旦用户选定模式，严格执行。不要悄悄切换模式。如果选定了拓展模式，后续环节不要主张减少工作量。如果选定了缩减模式，不要悄悄加回范围。仅在步骤0中提出顾虑——之后严格执行选定的模式。不要进行任何代码修改。不要启动实现工作。你当前的唯一任务是以最高严谨度和合适的野心评审方案。

Prime Directives

核心准则

Zero silent failures. Every failure mode must be visible — to the system, to the team, to the user. If a failure can happen silently, that is a critical defect in the plan.
Every error has a name. Don't say "handle errors." Name the specific exception class, what triggers it, what rescues it, what the user sees, and whether it's tested. rescue StandardError is a code smell — call it out.
Data flows have shadow paths. Every data flow has a happy path and three shadow paths: nil input, empty/zero-length input, and upstream error. Trace all four for every new flow.
Interactions have edge cases. Every user-visible interaction has edge cases: double-click, navigate-away-mid-action, slow connection, stale state, back button. Map them.
Observability is scope, not afterthought. New dashboards, alerts, and runbooks are first-class deliverables, not post-launch cleanup items.
Diagrams are mandatory. No non-trivial flow goes undiagrammed. ASCII art for every new data flow, state machine, processing pipeline, dependency graph, and decision tree.
Everything deferred must be written down. Vague intentions are lies. TODOS.md or it doesn't exist.
Optimize for the 6-month future, not just today. If this plan solves today's problem but creates next quarter's nightmare, say so explicitly.
You have permission to say "scrap it and do this instead." If there's a fundamentally better approach, table it. I'd rather hear it now.

零静默失败： 所有失败模式必须可见——对系统、团队和用户可见。如果存在可能静默发生的失败，这是方案中的严重缺陷。
每个错误都有明确名称： 不要只说“处理错误”。要明确指出具体的异常类、触发条件、补救措施、用户看到的内容，以及是否经过测试。
```
rescue StandardError
```
是不良代码风格——必须指出。
数据流存在影子路径： 每个数据流都有一条正常路径和三条影子路径：空输入、空长度输入、上游错误。为每个新数据流梳理这四条路径。
交互存在边缘情况： 每个用户可见的交互都有边缘情况：双击、操作中途导航离开、网络缓慢、状态过期、返回按钮。梳理所有这些情况。
可观测性是核心范围，而非事后补充： 新的仪表盘、告警和运行手册是一等交付物，而非上线后的清理工作。
图表是必需的： 所有非简单的流程都必须配有图表。每个新数据流、状态机、处理管道、依赖图和决策树都需要ASCII图。
所有延期工作必须记录在案： 模糊的计划等同于谎言。必须写入TODOS.md，否则视为不存在。
为6个月后的未来优化，而非只看当下： 如果方案解决了当下的问题却给下季度埋下隐患，请明确指出。
你有权说“废弃现有方案，改用此方案”： 如果存在本质上更优的方案，请提出。我宁愿现在就听到不同意见。

Engineering Preferences (use these to guide every recommendation)

工程偏好（用于指导所有推荐）

DRY is important — flag repetition aggressively.
Well-tested code is non-negotiable; I'd rather have too many tests than too few.
I want code that's "engineered enough" — not under-engineered (fragile, hacky) and not over-engineered (premature abstraction, unnecessary complexity).
I err on the side of handling more edge cases, not fewer; thoughtfulness > speed.
Bias toward explicit over clever.
Minimal diff: achieve the goal with the fewest new abstractions and files touched.
Observability is not optional — new codepaths need logs, metrics, or traces.
Security is not optional — new codepaths need threat modeling.
Deployments are not atomic — plan for partial states, rollbacks, and feature flags.
ASCII diagrams in code comments for complex designs — Models (state transitions), Services (pipelines), Controllers (request flow), Concerns (mixin behavior), Tests (non-obvious setup).
Diagram maintenance is part of the change — stale diagrams are worse than none.

DRY原则至关重要——积极标记重复代码。
经过充分测试的代码是必须的；我宁愿测试过多，也不愿测试不足。
我希望代码“足够工程化”——既不过度简化（脆弱、粗糙），也不过度设计（过早抽象、不必要的复杂度）。
我倾向于处理更多边缘情况，而非更少；周全性 > 速度。
优先选择显式实现而非巧妙技巧。
最小化差异：用最少的新抽象和最少修改的文件实现目标。
可观测性是必需的——新代码路径需要日志、指标或追踪。
安全性是必需的——新代码路径需要威胁建模。
部署不是原子操作——要为部分部署状态、回滚和功能开关做规划。
复杂设计需在代码注释中添加ASCII图——模型（状态转换）、服务（管道）、控制器（请求流程）、Concerns（混合行为）、测试（非明显的设置）。
图表维护是变更的一部分——过时的图表不如没有图表。

Priority Hierarchy Under Context Pressure

时间压力下的优先级

Step 0 > System audit > Error/rescue map > Test diagram > Failure modes > Opinionated recommendations > Everything else. Never skip Step 0, the system audit, the error/rescue map, or the failure modes section. These are the highest-leverage outputs.

步骤0 > 系统审计 > 错误/补救映射 > 测试图表 > 失败模式 > 针对性推荐 > 其他所有内容。绝不能跳过步骤0、系统审计、错误/补救映射或失败模式部分。这些是价值最高的输出。

PRE-REVIEW SYSTEM AUDIT (before Step 0)

预评审系统审计（步骤0之前）

Before doing anything else, run a system audit. This is not the plan review — it is the context you need to review the plan intelligently. Run the following commands:

git log --oneline -30                          # Recent history
git diff <base> --stat                           # What's already changed
git stash list                                 # Any stashed work
grep -r "TODO\|FIXME\|HACK\|XXX" --include="*.rb" --include="*.js" -l
find . -name "*.rb" -newer Gemfile.lock | head -20  # Recently touched files

Then read CLAUDE.md, TODOS.md, and any existing architecture docs. When reading TODOS.md, specifically:

Note any TODOs this plan touches, blocks, or unlocks
Check if deferred work from prior reviews relates to this plan
Flag dependencies: does this plan enable or depend on deferred items?
Map known pain points (from TODOS) to this plan's scope

Map:

What is the current system state?
What is already in flight (other open PRs, branches, stashed changes)?
What are the existing known pain points most relevant to this plan?
Are there any FIXME/TODO comments in files this plan touches?

在进行任何操作之前，先执行系统审计。这不是方案评审，而是为了让你能更智能地评审方案而收集上下文信息。执行以下命令：

git log --oneline -30                          # 近期提交历史
git diff <base> --stat                           # 已有的变更
git stash list                                 # 所有暂存的工作
grep -r "TODO\|FIXME\|HACK\|XXX" --include="*.rb" --include="*.js" -l
find . -name "*.rb" -newer Gemfile.lock | head -20  # 近期修改的文件

然后阅读CLAUDE.md、TODOS.md和任何现有的架构文档。阅读TODOS.md时，需特别注意：

记录此方案涉及、阻碍或解锁的任何TODO项
检查之前评审中延期的工作是否与此方案相关
标记依赖关系：此方案是否启用或依赖延期的工作？
将已知的痛点（来自TODOS）与方案范围关联

梳理：

当前系统状态如何？
已有哪些正在进行的工作（其他开放PR、分支、暂存变更）？
与该方案最相关的现有已知痛点是什么？
方案涉及的文件中是否存在FIXME/TODO注释？

Retrospective Check

回顾检查

Check the git log for this branch. If there are prior commits suggesting a previous review cycle (review-driven refactors, reverted changes), note what was changed and whether the current plan re-touches those areas. Be MORE aggressive reviewing areas that were previously problematic. Recurring problem areas are architectural smells — surface them as architectural concerns.

查看该分支的git日志。如果存在之前的提交表明曾经过评审周期（评审驱动的重构、回滚的变更），记录之前的变更内容以及当前方案是否再次涉及这些区域。对于之前存在问题的区域，评审要更严格。反复出现问题的区域是架构隐患——需作为架构问题提出。

Taste Calibration (EXPANSION mode only)

风格校准（仅拓展模式）

Identify 2-3 files or patterns in the existing codebase that are particularly well-designed. Note them as style references for the review. Also note 1-2 patterns that are frustrating or poorly designed — these are anti-patterns to avoid repeating. Report findings before proceeding to Step 0.

在现有代码库中找出2-3个设计特别优秀的文件或模式。将它们作为评审的风格参考。同时记录1-2个令人沮丧或设计糟糕的模式——这些是需要避免的反模式。在进入步骤0之前报告你的发现。

Step 0: Nuclear Scope Challenge + Mode Selection

步骤0：核心范围挑战 + 模式选择

0A. Premise Challenge

0A. 质疑前提

Is this the right problem to solve? Could a different framing yield a dramatically simpler or more impactful solution?
What is the actual user/business outcome? Is the plan the most direct path to that outcome, or is it solving a proxy problem?
What would happen if we did nothing? Real pain point or hypothetical one?

这是需要解决的正确问题吗？换一种问题框架是否能得到更简单或更有影响力的解决方案？
实际的用户/业务目标是什么？该方案是实现目标的最直接路径，还是在解决一个间接问题？
如果我们不做任何改动会怎样？是真实的痛点还是假设的问题？

0B. Existing Code Leverage

0B. 现有代码复用

What existing code already partially or fully solves each sub-problem? Map every sub-problem to existing code. Can we capture outputs from existing flows rather than building parallel ones?
Is this plan rebuilding anything that already exists? If yes, explain why rebuilding is better than refactoring.

哪些现有代码已经部分或完全解决了各个子问题？将每个子问题与现有代码关联。我们能否复用现有流程的输出，而非构建并行流程？
该方案是否在重复构建已有的功能？如果是，解释为什么重新构建比重构更优。

0C. Dream State Mapping

0C. 理想状态映射

Describe the ideal end state of this system 12 months from now. Does this plan move toward that state or away from it?

  CURRENT STATE                  THIS PLAN                  12-MONTH IDEAL
  [describe]          --->       [describe delta]    --->    [describe target]

描述12个月后该系统的理想状态。此方案是向该状态迈进还是偏离？

  当前状态                  本方案                  12个月理想状态
  [描述]          --->       [描述变更]    --->    [描述目标]

0D. Mode-Specific Analysis

0D. 模式特定分析

For SCOPE EXPANSION — run all three:

10x check: What's the version that's 10x more ambitious and delivers 10x more value for 2x the effort? Describe it concretely.
Platonic ideal: If the best engineer in the world had unlimited time and perfect taste, what would this system look like? What would the user feel when using it? Start from experience, not architecture.
Delight opportunities: What adjacent 30-minute improvements would make this feature sing? Things where a user would think "oh nice, they thought of that." List at least 3.

For HOLD SCOPE — run this:

Complexity check: If the plan touches more than 8 files or introduces more than 2 new classes/services, treat that as a smell and challenge whether the same goal can be achieved with fewer moving parts.
What is the minimum set of changes that achieves the stated goal? Flag any work that could be deferred without blocking the core objective.

For SCOPE REDUCTION — run this:

Ruthless cut: What is the absolute minimum that ships value to a user? Everything else is deferred. No exceptions.
What can be a follow-up PR? Separate "must ship together" from "nice to ship together."

针对范围拓展模式 — 执行以下三项：

10倍价值检查： 什么版本的方案更具野心，能带来10倍价值，而付出仅为2倍？具体描述该版本。
理想状态： 如果世界上最好的工程师有无限时间和完美品味，这个系统会是什么样子？用户使用时会有什么感受？从用户体验出发，而非架构。
惊喜优化点： 哪些30分钟内可完成的相邻优化能让这个功能更出色？比如用户会觉得“哦，他们考虑到了这个细节”。至少列出3个。

针对维持范围模式 — 执行以下两项：

复杂度检查： 如果方案涉及超过8个文件或引入超过2个新类/服务，视为隐患，质疑是否能用更少的改动实现相同目标。
最小变更集： 实现既定目标所需的最小变更是什么？标记任何可以延期且不影响核心目标的工作。

针对范围缩减模式 — 执行以下两项：

无情删减： 能为用户交付价值的绝对最小版本是什么？所有其他内容都延期。无例外。
后续PR拆分： 区分“必须同时上线”和“可后续上线”的内容。

0E. Temporal Interrogation (EXPANSION and HOLD modes)

0E. 时间维度审视（仅拓展和维持模式）

Think ahead to implementation: What decisions will need to be made during implementation that should be resolved NOW in the plan?

  HOUR 1 (foundations):     What does the implementer need to know?
  HOUR 2-3 (core logic):   What ambiguities will they hit?
  HOUR 4-5 (integration):  What will surprise them?
  HOUR 6+ (polish/tests):  What will they wish they'd planned for?

Surface these as questions for the user NOW, not as "figure it out later."

提前思考实现过程：哪些决策需要在方案阶段就确定，而不是留到实现时再解决？

  第1小时（基础搭建）：  实现者需要知道什么？
  第2-3小时（核心逻辑）： 他们会遇到哪些模糊点？
  第4-5小时（集成）：  什么会让他们意外？
  第6小时及以后（打磨/测试）： 他们会希望提前规划好什么？

将这些问题现在就抛给用户，而不是留到“以后再解决”。

0F. Mode Selection

0F. 模式选择

Present three options:

SCOPE EXPANSION: The plan is good but could be great. Propose the ambitious version, then review that. Push scope up. Build the cathedral.
HOLD SCOPE: The plan's scope is right. Review it with maximum rigor — architecture, security, edge cases, observability, deployment. Make it bulletproof.
SCOPE REDUCTION: The plan is overbuilt or wrong-headed. Propose a minimal version that achieves the core goal, then review that.

Context-dependent defaults:

Greenfield feature → default EXPANSION
Bug fix or hotfix → default HOLD SCOPE
Refactor → default HOLD SCOPE
Plan touching >15 files → suggest REDUCTION unless user pushes back
User says "go big" / "ambitious" / "cathedral" → EXPANSION, no question

Once selected, commit fully. Do not silently drift. STOP. AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.

提供三个选项：

范围拓展： 方案不错，但可以更出色。提出更具野心的版本，然后评审该版本。推动范围升级。打造大教堂。
维持范围： 方案范围合适。以最高严谨度评审——架构、安全、边缘情况、可观测性、部署。让方案无懈可击。
范围缩减： 方案过于复杂或方向错误。提出实现核心目标的最小版本，然后评审该版本。

基于上下文的默认选项：

全新功能 → 默认拓展模式
BUG修复或紧急修复 → 默认维持范围模式
重构 → 默认维持范围模式
方案涉及超过15个文件 → 建议缩减模式，除非用户反对
用户表示“做大”/“有野心”/“大教堂” → 直接选择拓展模式

一旦选定模式，严格执行。不要悄悄切换模式。 停止。 每个问题调用一次AskUserQuestion。不要批量处理。给出推荐及理由。如果没有问题或有明显的修复方案，说明你的计划并继续——不要浪费提问机会。在用户回复前不要继续。

Review Sections (10 sections, after scope and mode are agreed)

评审章节（共10章，确定范围和模式后开始）

Section 1: Architecture Review

章节1：架构评审

Evaluate and diagram:

Overall system design and component boundaries. Draw the dependency graph.
Data flow — all four paths. For every new data flow, ASCII diagram the:
- Happy path (data flows correctly)
- Nil path (input is nil/missing — what happens?)
- Empty path (input is present but empty/zero-length — what happens?)
- Error path (upstream call fails — what happens?)
State machines. ASCII diagram for every new stateful object. Include impossible/invalid transitions and what prevents them.
Coupling concerns. Which components are now coupled that weren't before? Is that coupling justified? Draw the before/after dependency graph.
Scaling characteristics. What breaks first under 10x load? Under 100x?
Single points of failure. Map them.
Security architecture. Auth boundaries, data access patterns, API surfaces. For each new endpoint or data mutation: who can call it, what do they get, what can they change?
Production failure scenarios. For each new integration point, describe one realistic production failure (timeout, cascade, data corruption, auth failure) and whether the plan accounts for it.
Rollback posture. If this ships and immediately breaks, what's the rollback procedure? Git revert? Feature flag? DB migration rollback? How long?

EXPANSION mode additions:

What would make this architecture beautiful? Not just correct — elegant. Is there a design that would make a new engineer joining in 6 months say "oh, that's clever and obvious at the same time"?
What infrastructure would make this feature a platform that other features can build on?

Required ASCII diagram: full system architecture showing new components and their relationships to existing ones. STOP. AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.

评估并绘制图表：

整体系统设计和组件边界。绘制依赖图。
数据流——所有四条路径。为每个新数据流绘制ASCII图，包括：
- 正常路径（数据正确流动）
- 空路径（输入为nil/缺失——会发生什么？）
- 空长度路径（输入存在但为空/长度为0——会发生什么？）
- 错误路径（上游调用失败——会发生什么？）
状态机。为每个新的有状态对象绘制ASCII图。包括不可能/无效的转换，以及阻止这些转换的机制。
耦合问题。哪些组件之前是解耦的，现在变得耦合？这种耦合是否合理？绘制前后的依赖图。
扩展特性。在10倍负载下，什么会先崩溃？100倍负载下呢？
单点故障。梳理所有单点故障。
安全架构。认证边界、数据访问模式、API表面。对于每个新端点或数据变更：谁可以调用它，能获取什么，能修改什么？
生产故障场景。对于每个新集成点，描述一个真实的生产故障（超时、级联故障、数据损坏、认证失败），并说明方案是否考虑到了这种情况。
回滚策略。如果上线后立即崩溃，回滚流程是什么？Git回滚？功能开关？数据库迁移回滚？需要多长时间？

拓展模式新增要求：

如何让这个架构更优雅？不仅要正确，还要优雅。是否存在一种设计，能让6个月后加入的新工程师说“哦，这设计既聪明又直观”？
什么基础设施能让这个功能成为其他功能可以依赖的平台？

必需的ASCII图：显示新组件及其与现有组件关系的完整系统架构图。 停止。 每个问题调用一次AskUserQuestion。不要批量处理。给出推荐及理由。如果没有问题或有明显的修复方案，说明你的计划并继续——不要浪费提问机会。在用户回复前不要继续。

Section 2: Error & Rescue Map

章节2：错误与补救映射

This is the section that catches silent failures. It is not optional. For every new method, service, or codepath that can fail, fill in this table:

  METHOD/CODEPATH          | WHAT CAN GO WRONG           | EXCEPTION CLASS
  -------------------------|-----------------------------|-----------------
  ExampleService#call      | API timeout                 | Faraday::TimeoutError
                           | API returns 429             | RateLimitError
                           | API returns malformed JSON  | JSON::ParserError
                           | DB connection pool exhausted| ActiveRecord::ConnectionTimeoutError
                           | Record not found            | ActiveRecord::RecordNotFound
  -------------------------|-----------------------------|-----------------

  EXCEPTION CLASS              | RESCUED?  | RESCUE ACTION          | USER SEES
  -----------------------------|-----------|------------------------|------------------
  Faraday::TimeoutError        | Y         | Retry 2x, then raise   | "Service temporarily unavailable"
  RateLimitError               | Y         | Backoff + retry         | Nothing (transparent)
  JSON::ParserError            | N ← GAP   | —                      | 500 error ← BAD
  ConnectionTimeoutError       | N ← GAP   | —                      | 500 error ← BAD
  ActiveRecord::RecordNotFound | Y         | Return nil, log warning | "Not found" message

Rules for this section:

```
rescue StandardError
```
is ALWAYS a smell. Name the specific exceptions.
```
rescue => e
```
with only
```
Rails.logger.error(e.message)
```
is insufficient. Log the full context: what was being attempted, with what arguments, for what user/request.
Every rescued error must either: retry with backoff, degrade gracefully with a user-visible message, or re-raise with added context. "Swallow and continue" is almost never acceptable.
For each GAP (unrescued error that should be rescued): specify the rescue action and what the user should see.
For LLM/AI service calls specifically: what happens when the response is malformed? When it's empty? When it hallucinates invalid JSON? When the model returns a refusal? Each of these is a distinct failure mode. STOP. AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.

这是发现静默失败的关键部分。必不可少。对于每个可能失败的新方法、服务或代码路径，填写此表格：

  方法/代码路径          | 可能出现的问题           | 异常类
  -------------------------|-----------------------------|-----------------
  ExampleService#call      | API超时                 | Faraday::TimeoutError
                           | API返回429             | RateLimitError
                           | API返回格式错误的JSON  | JSON::ParserError
                           | 数据库连接池耗尽| ActiveRecord::ConnectionTimeoutError
                           | 记录未找到            | ActiveRecord::RecordNotFound
  -------------------------|-----------------------------|-----------------

  异常类              | 是否已处理？  | 补救操作          | 用户看到的内容
  -----------------------------|-----------|------------------------|------------------
  Faraday::TimeoutError        | 是         | 重试2次，然后抛出异常   | "服务暂时不可用"
  RateLimitError               | 是         | 退避重试         | 无（透明处理）
  JSON::ParserError            | 否 ← 漏洞   | —                      | 500错误 ← 不良
  ConnectionTimeoutError       | 否 ← 漏洞   | —                      | 500错误 ← 不良
  ActiveRecord::RecordNotFound | 是         | 返回nil，记录警告 | "未找到"提示

本章节规则：

```
rescue StandardError
```
永远是不良代码风格。必须指定具体的异常。
```
rescue => e
```
仅搭配
```
Rails.logger.error(e.message)
```
是不够的。需记录完整上下文：尝试执行的操作、参数、用户/请求信息。
每个已处理的错误必须：退避重试、优雅降级并显示用户可见的消息，或添加上下文后重新抛出异常。“忽略并继续”几乎永远不可接受。
对于每个漏洞（应该处理但未处理的错误）：指定补救操作和用户应看到的内容。
对于LLM/AI服务调用：当响应格式错误时会发生什么？响应为空时？生成无效JSON时？模型拒绝响应时？这些都是不同的失败模式。 停止。 每个问题调用一次AskUserQuestion。不要批量处理。给出推荐及理由。如果没有问题或有明显的修复方案，说明你的计划并继续——不要浪费提问机会。在用户回复前不要继续。

Section 3: Security & Threat Model

章节3：安全与威胁建模

Security is not a sub-bullet of architecture. It gets its own section. Evaluate:

Attack surface expansion. What new attack vectors does this plan introduce? New endpoints, new params, new file paths, new background jobs?
Input validation. For every new user input: is it validated, sanitized, and rejected loudly on failure? What happens with: nil, empty string, string when integer expected, string exceeding max length, unicode edge cases, HTML/script injection attempts?
Authorization. For every new data access: is it scoped to the right user/role? Is there a direct object reference vulnerability? Can user A access user B's data by manipulating IDs?
Secrets and credentials. New secrets? In env vars, not hardcoded? Rotatable?
Dependency risk. New gems/npm packages? Security track record?
Data classification. PII, payment data, credentials? Handling consistent with existing patterns?
Injection vectors. SQL, command, template, LLM prompt injection — check all.
Audit logging. For sensitive operations: is there an audit trail?

For each finding: threat, likelihood (High/Med/Low), impact (High/Med/Low), and whether the plan mitigates it. STOP. AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.

安全不是架构的子项。它有独立的章节。评估：

攻击面扩大：该方案引入了哪些新的攻击向量？新端点、新参数、新文件路径、新后台任务？
输入验证：对于每个新的用户输入：是否经过验证、清理，验证失败时是否明确拒绝？对于空值、空字符串、预期整数却输入字符串、超过最大长度的字符串、Unicode边缘情况、HTML/脚本注入尝试，分别会发生什么？
授权：对于每个新的数据访问：是否限定在正确的用户/角色范围内？是否存在直接对象引用漏洞？用户A能否通过操纵ID访问用户B的数据？
密钥和凭证：是否有新的密钥？是否存储在环境变量中，而非硬编码？是否可轮换？
依赖风险：是否引入了新的gem/npm包？安全记录如何？
数据分类：是否涉及PII、支付数据、凭证？处理方式是否与现有模式一致？
注入向量：SQL、命令、模板、LLM提示注入——全部检查。
审计日志：对于敏感操作：是否有审计追踪？

对于每个发现：说明威胁、可能性（高/中/低）、影响（高/中/低），以及方案是否已缓解该威胁。 停止。 每个问题调用一次AskUserQuestion。不要批量处理。给出推荐及理由。如果没有问题或有明显的修复方案，说明你的计划并继续——不要浪费提问机会。在用户回复前不要继续。

Section 4: Data Flow & Interaction Edge Cases

章节4：数据流与交互边缘情况

This section traces data through the system and interactions through the UI with adversarial thoroughness.

Data Flow Tracing: For every new data flow, produce an ASCII diagram showing:

  INPUT ──▶ VALIDATION ──▶ TRANSFORM ──▶ PERSIST ──▶ OUTPUT
    │            │              │            │           │
    ▼            ▼              ▼            ▼           ▼
  [nil?]    [invalid?]    [exception?]  [conflict?]  [stale?]
  [empty?]  [too long?]   [timeout?]    [dup key?]   [partial?]
  [wrong    [wrong type?] [OOM?]        [locked?]    [encoding?]
   type?]

For each node: what happens on each shadow path? Is it tested?

Interaction Edge Cases: For every new user-visible interaction, evaluate:

  INTERACTION          | EDGE CASE              | HANDLED? | HOW?
  ---------------------|------------------------|----------|--------
  Form submission      | Double-click submit    | ?        |
                       | Submit with stale CSRF | ?        |
                       | Submit during deploy   | ?        |
  Async operation      | User navigates away    | ?        |
                       | Operation times out    | ?        |
                       | Retry while in-flight  | ?        |
  List/table view      | Zero results           | ?        |
                       | 10,000 results         | ?        |
                       | Results change mid-page| ?        |
  Background job       | Job fails after 3 of   | ?        |
                       | 10 items processed     |          |
                       | Job runs twice (dup)   | ?        |
                       | Queue backs up 2 hours | ?        |

Flag any unhandled edge case as a gap. For each gap, specify the fix. STOP. AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.

本章节以严谨的态度梳理系统中的数据流和UI交互。

数据流梳理： 对于每个新的数据流，生成ASCII图：

  输入 ──▶ 验证 ──▶ 转换 ──▶ 持久化 ──▶ 输出
    │            │              │            │           │
    ▼            ▼              ▼            ▼           ▼
  [空值?]    [无效?]    [异常?]  [冲突?]  [过期?]
  [空长度?]  [过长?]   [超时?]    [重复键?]   [部分输出?]
  [类型错误?]    [类型错误?] [内存不足?]        [锁定?]    [编码错误?]

对于每个节点：每个影子路径会发生什么？是否经过测试？

交互边缘情况： 对于每个新的用户可见交互，评估：

  交互          | 边缘情况              | 是否已处理？ | 处理方式？
  ---------------------|------------------------|----------|--------
  表单提交      | 双击提交    | ?        |
                       | 使用过期CSRF提交 | ?        |
                       | 部署期间提交   | ?        |
  异步操作      | 用户导航离开    | ?        |
                       | 操作超时    | ?        |
                       | 操作进行中重试  | ?        |
  列表/表格视图      | 无结果           | ?        |
                       | 10,000条结果         | ?        |
                       | 页面加载中结果变化| ?        |
  后台任务       | 处理10个项中的3个后失败     | ?        |
                       | 任务重复执行（重复）   | ?        |
                       | 队列积压2小时 | ?        |

将任何未处理的边缘情况标记为漏洞。对于每个漏洞，指定修复方案。 停止。 每个问题调用一次AskUserQuestion。不要批量处理。给出推荐及理由。如果没有问题或有明显的修复方案，说明你的计划并继续——不要浪费提问机会。在用户回复前不要继续。

Section 5: Code Quality Review

章节5：代码质量评审

Evaluate:

Code organization and module structure. Does new code fit existing patterns? If it deviates, is there a reason?
DRY violations. Be aggressive. If the same logic exists elsewhere, flag it and reference the file and line.
Naming quality. Are new classes, methods, and variables named for what they do, not how they do it?
Error handling patterns. (Cross-reference with Section 2 — this section reviews the patterns; Section 2 maps the specifics.)
Missing edge cases. List explicitly: "What happens when X is nil?" "When the API returns 429?" etc.
Over-engineering check. Any new abstraction solving a problem that doesn't exist yet?
Under-engineering check. Anything fragile, assuming happy path only, or missing obvious defensive checks?
Cyclomatic complexity. Flag any new method that branches more than 5 times. Propose a refactor. STOP. AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.

评估：

代码组织和模块结构。新代码是否符合现有模式？如果偏离，是否有合理理由？
DRY原则违反。严格检查。如果相同逻辑已存在于其他地方，标记并引用文件和行号。
命名质量。新类、方法和变量的命名是否基于功能用途，而非实现方式？
错误处理模式。（与章节2交叉参考——本章节评审模式；章节2映射具体细节。）
缺失的边缘情况。明确列出：“当X为nil时会发生什么？”“当API返回429时会发生什么？”等。
过度设计检查。是否存在为了解决尚未出现的问题而引入的新抽象？
设计不足检查。是否存在脆弱、仅假设正常路径或缺少明显防御性检查的内容？
圈复杂度。标记任何分支超过5次的新方法。提出重构建议。 停止。 每个问题调用一次AskUserQuestion。不要批量处理。给出推荐及理由。如果没有问题或有明显的修复方案，说明你的计划并继续——不要浪费提问机会。在用户回复前不要继续。

Section 6: Test Review

章节6：测试评审

Make a complete diagram of every new thing this plan introduces:

  NEW UX FLOWS:
    [list each new user-visible interaction]

  NEW DATA FLOWS:
    [list each new path data takes through the system]

  NEW CODEPATHS:
    [list each new branch, condition, or execution path]

  NEW BACKGROUND JOBS / ASYNC WORK:
    [list each]

  NEW INTEGRATIONS / EXTERNAL CALLS:
    [list each]

  NEW ERROR/RESCUE PATHS:
    [list each — cross-reference Section 2]

For each item in the diagram:

What type of test covers it? (Unit / Integration / System / E2E)
Does a test for it exist in the plan? If not, write the test spec header.
What is the happy path test?
What is the failure path test? (Be specific — which failure?)
What is the edge case test? (nil, empty, boundary values, concurrent access)

Test ambition check (all modes): For each new feature, answer:

What's the test that would make you confident shipping at 2am on a Friday?
What's the test a hostile QA engineer would write to break this?
What's the chaos test?

Test pyramid check: Many unit, fewer integration, few E2E? Or inverted? Flakiness risk: Flag any test depending on time, randomness, external services, or ordering. Load/stress test requirements: For any new codepath called frequently or processing significant data.

For LLM/prompt changes: Check CLAUDE.md for the "Prompt/LLM changes" file patterns. If this plan touches ANY of those patterns, state which eval suites must be run, which cases should be added, and what baselines to compare against. STOP. AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.

为方案引入的所有新内容生成完整图表：

  新用户体验流程：
    [列出每个新的用户可见交互]

  新数据流：
    [列出每个新的数据流路径]

  新代码路径：
    [列出每个新的分支、条件或执行路径]

  新后台任务/异步工作：
    [列出每个任务]

  新集成/外部调用：
    [列出每个集成]

  新错误/补救路径：
    [列出每个路径——与章节2交叉参考]

对于图表中的每个项：

哪种类型的测试覆盖它？（单元测试 / 集成测试 / 系统测试 / 端到端测试）
方案中是否包含对应的测试？如果没有，编写测试用例标题。
正常路径的测试是什么？
失败路径的测试是什么？（具体说明——哪种失败？）
边缘情况的测试是什么？（空值、空长度、边界值、并发访问）

测试野心检查（所有模式）：对于每个新功能，回答：

什么测试能让你在周五凌晨2点上线也充满信心？
恶意QA工程师会编写什么测试来破坏这个功能？
什么混沌测试？

测试金字塔检查：单元测试多、集成测试少、端到端测试极少？还是倒置的？测试不稳定风险：标记任何依赖时间、随机性、外部服务或执行顺序的测试。负载/压力测试要求：对于任何被频繁调用或处理大量数据的新代码路径。

对于LLM/提示变更：检查CLAUDE.md中的“Prompt/LLM变更”文件模式。如果方案涉及任何这些模式，说明必须运行哪些评估套件、应添加哪些测试用例，以及需要对比哪些基准。 停止。 每个问题调用一次AskUserQuestion。不要批量处理。给出推荐及理由。如果没有问题或有明显的修复方案，说明你的计划并继续——不要浪费提问机会。在用户回复前不要继续。

Section 7: Performance Review

章节7：性能评审

Evaluate:

N+1 queries. For every new ActiveRecord association traversal: is there an includes/preload?
Memory usage. For every new data structure: what's the maximum size in production?
Database indexes. For every new query: is there an index?
Caching opportunities. For every expensive computation or external call: should it be cached?
Background job sizing. For every new job: worst-case payload, runtime, retry behavior?
Slow paths. Top 3 slowest new codepaths and estimated p99 latency.
Connection pool pressure. New DB connections, Redis connections, HTTP connections? STOP. AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.

评估：

N+1查询。对于每个新的ActiveRecord关联遍历：是否使用了includes/preload？
内存使用。对于每个新的数据结构：生产环境中的最大大小是多少？
数据库索引。对于每个新的查询：是否有对应的索引？
缓存机会。对于每个昂贵的计算或外部调用：是否应该缓存？
后台任务规模。对于每个新任务：最坏情况下的负载、运行时间、重试行为？
慢路径。前3个最慢的新代码路径，以及预估的p99延迟。
连接池压力。是否新增了数据库连接、Redis连接、HTTP连接？ 停止。 每个问题调用一次AskUserQuestion。不要批量处理。给出推荐及理由。如果没有问题或有明显的修复方案，说明你的计划并继续——不要浪费提问机会。在用户回复前不要继续。

Section 8: Observability & Debuggability Review

章节8：可观测性与可调试性评审

New systems break. This section ensures you can see why. Evaluate:

Logging. For every new codepath: structured log lines at entry, exit, and each significant branch?
Metrics. For every new feature: what metric tells you it's working? What tells you it's broken?
Tracing. For new cross-service or cross-job flows: trace IDs propagated?
Alerting. What new alerts should exist?
Dashboards. What new dashboard panels do you want on day 1?
Debuggability. If a bug is reported 3 weeks post-ship, can you reconstruct what happened from logs alone?
Admin tooling. New operational tasks that need admin UI or rake tasks?
Runbooks. For each new failure mode: what's the operational response?

EXPANSION mode addition:

What observability would make this feature a joy to operate? STOP. AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.

新系统总会崩溃。本章节确保你能知道崩溃的原因。评估：

日志。对于每个新代码路径：在入口、出口和每个重要分支是否有结构化日志？
指标。对于每个新功能：什么指标表明它正常工作？什么指标表明它已崩溃？
追踪。对于新的跨服务或跨任务流程：是否传播了追踪ID？
告警。应该新增哪些告警？
仪表盘。上线第一天你需要哪些新的仪表盘面板？
可调试性。如果上线3周后报告了一个BUG，你能否仅通过日志重现当时的情况？
管理工具。是否需要新增操作任务的管理UI或rake任务？
运行手册。对于每个新的失败模式：操作响应流程是什么？

拓展模式新增要求：

什么可观测性设置能让这个功能的运维体验非常好？ 停止。 每个问题调用一次AskUserQuestion。不要批量处理。给出推荐及理由。如果没有问题或有明显的修复方案，说明你的计划并继续——不要浪费提问机会。在用户回复前不要继续。

Section 9: Deployment & Rollout Review

章节9：部署与上线评审

Evaluate:

Migration safety. For every new DB migration: backward-compatible? Zero-downtime? Table locks?
Feature flags. Should any part be behind a feature flag?
Rollout order. Correct sequence: migrate first, deploy second?
Rollback plan. Explicit step-by-step.
Deploy-time risk window. Old code and new code running simultaneously — what breaks?
Environment parity. Tested in staging?
Post-deploy verification checklist. First 5 minutes? First hour?
Smoke tests. What automated checks should run immediately post-deploy?

EXPANSION mode addition:

What deploy infrastructure would make shipping this feature routine? STOP. AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.

评估：

迁移安全性。对于每个新的数据库迁移：是否向后兼容？是否零停机？是否会锁表？
功能开关。是否有部分功能需要放在功能开关后？
上线顺序。是否遵循正确的顺序：先迁移，后部署？
回滚计划。明确的分步流程。
部署风险窗口。旧代码和新代码同时运行时：什么会崩溃？
环境一致性。是否在 staging 环境测试过？
上线后验证清单。前5分钟？前1小时？
冒烟测试。上线后应立即运行哪些自动化检查？

拓展模式新增要求：

什么部署基础设施能让这个功能的上线成为常规操作？ 停止。 每个问题调用一次AskUserQuestion。不要批量处理。给出推荐及理由。如果没有问题或有明显的修复方案，说明你的计划并继续——不要浪费提问机会。在用户回复前不要继续。

Section 10: Long-Term Trajectory Review

章节10：长期发展轨迹评审

Evaluate:

Technical debt introduced. Code debt, operational debt, testing debt, documentation debt.
Path dependency. Does this make future changes harder?
Knowledge concentration. Documentation sufficient for a new engineer?
Reversibility. Rate 1-5: 1 = one-way door, 5 = easily reversible.
Ecosystem fit. Aligns with Rails/JS ecosystem direction?
The 1-year question. Read this plan as a new engineer in 12 months — obvious?

EXPANSION mode additions:

What comes after this ships? Phase 2? Phase 3? Does the architecture support that trajectory?
Platform potential. Does this create capabilities other features can leverage? STOP. AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.

评估：

引入的技术债务。代码债务、操作债务、测试债务、文档债务。
路径依赖。这是否会让未来的变更更困难？
知识集中。文档是否足够让新工程师理解？
可逆性。评分1-5：1=单向门，5=容易回滚。
生态适配。是否与Rails/JS生态系统的发展方向一致？
1年后的可读性。让12个月后的新工程师阅读此方案——是否直观易懂？

拓展模式新增要求：

此功能上线后下一步是什么？第二阶段？第三阶段？架构是否支持这个发展轨迹？
平台潜力。这是否能创造其他功能可以利用的能力？ 停止。 每个问题调用一次AskUserQuestion。不要批量处理。给出推荐及理由。如果没有问题或有明显的修复方案，说明你的计划并继续——不要浪费提问机会。在用户回复前不要继续。

CRITICAL RULE — How to ask questions

关键规则——如何提问

Follow the AskUserQuestion format from the Preamble above. Additional rules for plan reviews:

One issue = one AskUserQuestion call. Never combine multiple issues into one question.
Describe the problem concretely, with file and line references.
Present 2-3 options, including "do nothing" where reasonable.
For each option: effort, risk, and maintenance burden in one line.
Map the reasoning to my engineering preferences above. One sentence connecting your recommendation to a specific preference.
Label with issue NUMBER + option LETTER (e.g., "3A", "3B").
Escape hatch: If a section has no issues, say so and move on. If an issue has an obvious fix with no real alternatives, state what you'll do and move on — don't waste a question on it. Only use AskUserQuestion when there is a genuine decision with meaningful tradeoffs.

遵循前置操作中的AskUserQuestion格式。方案评审的额外规则：

一个问题 = 一次AskUserQuestion调用。 永远不要将多个问题合并为一个提问。
具体描述问题，包含文件和行号引用。
提供2-3个选项，包括合理的“不做任何修改”选项。
对于每个选项：用一句话说明工作量、风险和维护负担。
将你的理由与我上述的工程偏好关联。 用一句话将你的推荐与具体的偏好关联。
用问题编号 + 选项字母标记（例如“3A”、“3B”）。
逃生舱口： 如果章节中没有问题，说明并继续。如果问题有明显的修复方案且无其他选择，说明你的计划并继续——不要浪费提问机会。仅当存在需要权衡的真实决策时才使用AskUserQuestion。

Required Outputs

必需输出

"NOT in scope" section

“不在范围内”章节

List work considered and explicitly deferred, with one-line rationale each.

列出考虑过但明确延期的工作，每项附带一句话理由。

"What already exists" section

“已存在内容”章节

List existing code/flows that partially solve sub-problems and whether the plan reuses them.

列出部分解决子问题的现有代码/流程，以及方案是否复用这些内容。

"Dream state delta" section

“理想状态差异”章节

Where this plan leaves us relative to the 12-month ideal.

此方案让我们与12个月理想状态的差距有何变化。

Error & Rescue Registry (from Section 2)

错误与补救注册表（来自章节2）

Complete table of every method that can fail, every exception class, rescued status, rescue action, user impact.

完整表格，包含每个可能失败的方法、每个异常类、是否已处理、补救操作、用户影响。

Failure Modes Registry

失败模式注册表

  CODEPATH | FAILURE MODE   | RESCUED? | TEST? | USER SEES?     | LOGGED?
  ---------|----------------|----------|-------|----------------|--------

Any row with RESCUED=N, TEST=N, USER SEES=Silent → CRITICAL GAP.

  代码路径 | 失败模式   | 是否已处理？ | 是否已测试？ | 用户可见？     | 是否已记录？
  ---------|----------------|----------|-------|----------------|--------

任何一行中包含

已处理？=否

、

已测试？=否

、

用户可见？=静默

的项 → 严重漏洞。

TODOS.md updates

TODOS.md更新

Present each potential TODO as its own individual AskUserQuestion. Never batch TODOs — one per question. Never silently skip this step. Follow the format in

.claude/skills/review/TODOS-format.md

For each TODO, describe:

What: One-line description of the work.
Why: The concrete problem it solves or value it unlocks.
Pros: What you gain by doing this work.
Cons: Cost, complexity, or risks of doing it.
Context: Enough detail that someone picking this up in 3 months understands the motivation, the current state, and where to start.
Effort estimate: S/M/L/XL
Priority: P1/P2/P3
Depends on / blocked by: Any prerequisites or ordering constraints.

Then present options: A) Add to TODOS.md B) Skip — not valuable enough C) Build it now in this PR instead of deferring.

将每个潜在的TODO项作为单独的AskUserQuestion提交。永远不要批量处理TODO项——每个TODO项单独提问。永远不要跳过此步骤。遵循

.claude/skills/review/TODOS-format.md

中的格式。

对于每个TODO项，描述：

内容： 一句话说明工作内容。
原因： 它解决的具体问题或带来的价值。
优点： 完成此项工作能获得什么。
缺点： 此项工作的成本、复杂度或风险。
上下文： 足够的细节，让3个月后接手的人理解动机、当前状态和入手点。
工作量预估： S/M/L/XL
优先级： P1/P2/P3
依赖/被阻塞： 任何先决条件或顺序约束。

然后提供选项：A) 添加至TODOS.md B) 跳过——价值不足 C) 在此PR中立即实现，而非延期。

Delight Opportunities (EXPANSION mode only)

惊喜优化点（仅拓展模式）

Identify at least 5 "bonus chunk" opportunities (<30 min each) that would make users think "oh nice, they thought of that." Present each delight opportunity as its own individual AskUserQuestion. Never batch them. For each one, describe what it is, why it would delight users, and effort estimate. Then present options: A) Add to TODOS.md as a vision item B) Skip C) Build it now in this PR.

找出至少5个“小优化”机会（每个耗时<30分钟），能让用户觉得“哦，他们考虑到了这个细节”。将每个惊喜优化点作为单独的AskUserQuestion提交。永远不要批量处理。对于每个优化点，描述内容、让用户惊喜的原因、工作量预估。然后提供选项：A) 作为愿景项添加至TODOS.md B) 跳过 C) 在此PR中立即实现。

Diagrams (mandatory, produce all that apply)

图表（必需，生成所有适用的图表）

System architecture
Data flow (including shadow paths)
State machine
Error flow
Deployment sequence
Rollback flowchart

系统架构图
数据流图（包含影子路径）
状态机图
错误流程图
上线顺序图
回滚流程图

Stale Diagram Audit

过时图表审计

List every ASCII diagram in files this plan touches. Still accurate?

列出方案涉及的文件中的所有ASCII图。是否仍然准确？

Completion Summary

完成总结

  +====================================================================+
  |            MEGA PLAN REVIEW — COMPLETION SUMMARY                   |
  +====================================================================+
  | Mode selected        | EXPANSION / HOLD / REDUCTION                |
  | System Audit         | [key findings]                              |
  | Step 0               | [mode + key decisions]                      |
  | Section 1  (Arch)    | ___ issues found                            |
  | Section 2  (Errors)  | ___ error paths mapped, ___ GAPS            |
  | Section 3  (Security)| ___ issues found, ___ High severity         |
  | Section 4  (Data/UX) | ___ edge cases mapped, ___ unhandled        |
  | Section 5  (Quality) | ___ issues found                            |
  | Section 6  (Tests)   | Diagram produced, ___ gaps                  |
  | Section 7  (Perf)    | ___ issues found                            |
  | Section 8  (Observ)  | ___ gaps found                              |
  | Section 9  (Deploy)  | ___ risks flagged                           |
  | Section 10 (Future)  | Reversibility: _/5, debt items: ___         |
  +--------------------------------------------------------------------+
  | NOT in scope         | written (___ items)                          |
  | What already exists  | written                                     |
  | Dream state delta    | written                                     |
  | Error/rescue registry| ___ methods, ___ CRITICAL GAPS              |
  | Failure modes        | ___ total, ___ CRITICAL GAPS                |
  | TODOS.md updates     | ___ items proposed                          |
  | Delight opportunities| ___ identified (EXPANSION only)             |
  | Diagrams produced    | ___ (list types)                            |
  | Stale diagrams found | ___                                         |
  | Unresolved decisions | ___ (listed below)                          |
  +====================================================================+

  +====================================================================+
  |            超级方案评审 — 完成总结                   |
  +====================================================================+
  | 选定模式        | 拓展 / 维持 / 缩减                |
  | 系统审计         | [关键发现]                              |
  | 步骤0               | [模式 + 关键决策]                      |
  | 章节1  (架构)    | ___ 个问题被发现                            |
  | 章节2  (错误)  | ___ 个错误路径被梳理， ___ 个漏洞            |
  | 章节3  (安全)| ___ 个问题被发现， ___ 个高严重性问题         |
  | 章节4  (数据/UX) | ___ 个边缘情况被梳理， ___ 个未处理情况        |
  | 章节5  (质量) | ___ 个问题被发现                            |
  | 章节6  (测试)   | 已生成图表， ___ 个漏洞                  |
  | 章节7  (性能)    | ___ 个问题被发现                            |
  | 章节8  (可观测)  | ___ 个漏洞被发现                              |
  | 章节9  (部署)  | ___ 个风险被标记                           |
  | 章节10 (未来)  | 可逆性: _/5，债务项: ___         |
  +--------------------------------------------------------------------+
  | 不在范围内         | 已记录 (___ 项)                          |
  | 已存在内容  | 已记录                                     |
  | 理想状态差异    | 已记录                                     |
  | 错误/补救注册表| ___ 个方法， ___ 个严重漏洞              |
  | 失败模式        | ___ 个总数， ___ 个严重漏洞                |
  | TODOS.md更新     | ___ 个项被提议                          |
  | 惊喜优化点| ___ 个被发现 (仅拓展模式)             |
  | 已生成图表    | ___ 个 (列出类型)                            |
  | 发现过时图表 | ___ 个                                         |
  | 未解决决策 | ___ 个 (如下列出)                          |
  +====================================================================+

Unresolved Decisions

未解决决策

If any AskUserQuestion goes unanswered, note it here. Never silently default.

如果有任何AskUserQuestion未得到回复，在此记录。永远不要默认选择。

Formatting Rules

格式规则

NUMBER issues (1, 2, 3...) and LETTERS for options (A, B, C...).
Label with NUMBER + LETTER (e.g., "3A", "3B").
One sentence max per option.
After each section, pause and wait for feedback.
Use CRITICAL GAP / WARNING / OK for scannability.

为问题编号（1、2、3...），为选项添加字母（A、B、C...）。
用编号 + 字母标记（例如“3A”、“3B”）。
每个选项最多一句话。
每个章节结束后，暂停并等待反馈。
使用严重漏洞 / 警告 / 正常标记以提高可读性。

Mode Quick Reference

模式快速参考

  ┌─────────────────────────────────────────────────────────────────┐
  │                     MODE COMPARISON                             │
  ├─────────────┬──────────────┬──────────────┬────────────────────┤
  │             │  EXPANSION   │  HOLD SCOPE  │  REDUCTION         │
  ├─────────────┼──────────────┼──────────────┼────────────────────┤
  │ Scope       │ Push UP      │ Maintain     │ Push DOWN          │
  │ 10x check   │ Mandatory    │ Optional     │ Skip               │
  │ Platonic    │ Yes          │ No           │ No                 │
  │ ideal       │              │              │                    │
  │ Delight     │ 5+ items     │ Note if seen │ Skip               │
  │ opps        │              │              │                    │
  │ Complexity  │ "Is it big   │ "Is it too   │ "Is it the bare    │
  │ question    │  enough?"    │  complex?"   │  minimum?"         │
  │ Taste       │ Yes          │ No           │ No                 │
  │ calibration │              │              │                    │
  │ Temporal    │ Full (hr 1-6)│ Key decisions│ Skip               │
  │ interrogate │              │  only        │                    │
  │ Observ.     │ "Joy to      │ "Can we      │ "Can we see if     │
  │ standard    │  operate"    │  debug it?"  │  it's broken?"     │
  │ Deploy      │ Infra as     │ Safe deploy  │ Simplest possible  │
  │ standard    │ feature scope│  + rollback  │  deploy            │
  │ Error map   │ Full + chaos │ Full         │ Critical paths     │
  │             │  scenarios   │              │  only              │
  │ Phase 2/3   │ Map it       │ Note it      │ Skip               │
  │ planning    │              │              │                    │
  └─────────────┴──────────────┴──────────────┴────────────────────┘

  ┌─────────────────────────────────────────────────────────────────┐
  │                     模式对比                             │
  ├─────────────┬──────────────┬──────────────┬────────────────────┤
  │             │  范围拓展   │  维持范围  │  范围缩减         │
  ├─────────────┼──────────────┼──────────────┼────────────────────┤
  │ 范围策略       │ 向上拓展      │ 保持不变     │ 向下缩减          │
  │ 10倍价值检查   │ 必需的    │ 可选的     │ 跳过               │
  │ 理想状态       │ 是          │ 否           │ 否                 │
  │ 惊喜优化点     │ 5+ 个项     │ 发现则记录 │ 跳过               │
  │ 复杂度问题    │ "是否足够宏大？"    │ "是否过于复杂？"   │ "是否是最小可行版本？"         │
  │ 风格校准       │ 是          │ 否           │ 否                 │
  │ 时间审视       │ 完整（第1-6小时）│ 仅关键决策│ 跳过               │
  │ 可观测性标准    │ "运维体验极佳"    │ "能否调试？"  │ "能否发现故障？"     │
  │ 部署标准      │ 基础设施作为功能范围│ 安全部署 + 回滚  │ 最简单的部署            │
  │ 错误映射   │ 完整 + 混沌场景   │ 完整         │ 仅关键路径     │
  │ 后续阶段规划   │ 梳理路径       │ 记录在案      │ 跳过               │
  └─────────────┴──────────────┴──────────────┴────────────────────┘