scope-triage

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Scope Triage Before Design

设计前的范围分类

Turn a request into either an implementation contract or a fully formed design. Classification comes first, always: one turn that states a hypothesis, records assumptions, and picks a route. Only Route C runs the full design cycle — A and B exist so an already-specified change is not taxed with a design.

将需求转化为实现契约或完整设计。始终先进行分类：通过一轮分析提出假设、记录前提条件并选择路径。只有C路径需要完整的设计周期——A和B路径的存在是为了避免让已明确的变更额外承担设计成本。

Step 0 — Scope Check

步骤0——范围检查

Do this before any other action, in a single turn, for every request.

Hypothesis with confidence. One sentence naming what the user wants to end up with, plus an honest 0-100% confidence. Below 70%, add one line stating what is missing.
Assumption ledger. List the assumptions the answer rests on; mark each
```
verified
```
(confirmed in code or docs this session),
```
assumed
```
, or
```
contradicted
```
(checked and found false). Retrieve repository facts yourself; ask only user decisions. Any
```
contradicted
```
entry means Route C.
Classify against the route conditions below.
Announce the route in one self-contained sentence — it must repeat the target contract in full, with the literal values, names, and numbers from the request, and read correctly on its own.

Route C (full design) — if ANY of these hold:

requirements are ambiguous or contradictory;
the user-visible outcome or the success criteria are still undefined;
there is a product, UX, or visual decision to make;
two or more materially different architectural approaches exist;
the change creates a new capability or public contract, or materially alters data flow;
you would have to pick a behavior the user never specified;
an
```
assumed
```
entry about product, UX, or a public contract is still unverified;
you cannot predict the user's answers to the next three questions you would ask.

Route A (direct implementation) — only if ALL of these hold:

the user stated the target outcome explicitly;
the done criterion is unambiguous and checkable by a test or a deterministic check;
no product, UX, or architectural choice is unresolved;
the change is a localized fix or a mechanical transformation of an existing contract;
you are not widening scope or adding behavior of your own;
every assumption affecting the result is marked
```
verified
```
.

Route B (light spec) — the boundary: Route A conditions hold, but the change is large-scale (a migration, many consumers) or exactly one compatibility question is open.

Uncertainty rule: any uncertainty about the classification means Route C. File count and line count are NOT criteria in either direction.

User overrides, honored from the current message only:

"skip design", "just do it", "no spec" → Route A is permitted despite doubt, but name in one sentence the risk this instruction takes off your hands.
"design this properly", "grill me", "full cycle" → Route C regardless of classification.

Non-interactive runs (CI, autonomous loop, subagent with no channel to the user) cannot run Route C. If classification yields Route A, proceed; otherwise stop and report the blocker. Do NOT guess past it.

在采取任何其他行动之前，针对每个需求先完成这一步，只需一轮分析。

带置信度的假设。用一句话说明用户最终想要的结果，并给出0-100%的真实置信度。如果置信度低于70%，补充一行说明缺失的信息。
前提条件记录。列出答案所基于的前提条件；标记每个条件为
```
verified
```
（本次会话中已在代码或文档中确认）、
```
assumed
```
（假设）或
```
contradicted
```
（已核实为错误）。自行获取仓库中的事实信息；仅询问用户的决策。任何
```
contradicted
```
条目意味着需走C路径。
根据以下路径条件进行分类。
明确宣布所选路径——用一句独立的话说明，必须完整复述目标契约，包含需求中的字面数值、名称和数字，且单独阅读时表意清晰。

C路径（完整设计）——满足以下任一条件时：

需求模糊或存在矛盾；
用户可见的结果或成功标准仍未定义；
需要做出产品、UX或视觉设计决策；
存在两种或更多本质不同的架构实现方案；
变更会创建新功能或公开契约，或实质性改变数据流；
你必须选择用户未明确说明的行为；
关于产品、UX或公开契约的
```
assumed
```
条目仍未验证；
你无法预测用户对接下来三个问题的回答。

A路径（直接实现）——必须同时满足以下所有条件：

用户明确说明了目标结果；
完成标准清晰明确，可通过测试或确定性检查验证；
产品、UX或架构方面无未解决的选择；
变更是局部修复或对现有契约的机械性改造；
你未扩大范围或自行添加行为；
所有影响结果的前提条件均标记为
```
verified
```
。

B路径（轻量级规格）——边界情况： 满足A路径的所有条件，但变更规模较大（如迁移、涉及大量消费者）或存在一个未解决的兼容性问题。

不确定性规则： 任何对分类的不确定性都意味着需走C路径。文件数量和代码行数不是判断标准。

用户覆盖规则，仅适用于当前消息：

"跳过设计"、"直接做"、"不要规格" → 即使存在疑虑也允许走A路径，但需用一句话说明此指令将风险转移给了你。
"妥善设计"、"详细询问"、"完整流程" → 无论分类结果如何，均走C路径。

非交互式运行（CI、自主循环、无用户沟通渠道的子Agent）无法执行C路径。如果分类结果为A路径，则继续；否则停止并报告阻塞问题。切勿猜测。

Route A — Direct Implementation

A路径——直接实现

Say one sentence: the repeated target contract, the done criterion, and the route.
The done criterion carries the literal values from the request, and whatever proves it — a test, a command, a grep — must reproduce that exact case, not a convenient neighbouring one. A bug reported as "asked for 10, got 9" is proven by a test asserting 10, not by one asserting 5.
Continue with the matching implementation skill — TDD for behavior changes, debugging for bugs with known expected behavior, a direct edit for configuration. No spec file, no plan, no approval gate.
If an unresolved product or architectural decision surfaces mid-work, stop and switch to Route C — mandatory, not a judgment call.

用一句话说明：复述目标契约、完成标准和所选路径。
完成标准需包含需求中的字面数值，用于验证的测试、命令或grep操作必须完全匹配该案例，而非相近案例。例如，报告为"请求10，得到9"的bug，需通过断言10的测试验证，而非断言5的测试。
继续使用匹配的实现技能——行为变更用TDD，已知预期行为的bug用调试，配置变更直接编辑。无需规格文件、计划或审批环节。
如果在工作过程中出现未解决的产品或架构决策，必须停止并切换到C路径——这是强制要求，而非主观判断。

Route B — Light Spec

B路径——轻量级规格

Write a 5-10 line spec: goal, target contract, out of scope, done criterion.
Settle the single open compatibility question with the user, then implement.
No full design cycle, no design approval loop, no mandatory
```
plan-crafting
```
handoff.

编写5-10行的规格：目标、目标契约、范围外内容、完成标准。
与用户解决唯一未解决的兼容性问题，然后开始实现。
无需完整设计周期、设计审批循环或强制的
```
plan-crafting
```
移交。

Route C — Full Design

C路径——完整设计

<HARD-GATE> Inside Route C, do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project routed here, regardless of perceived simplicity. </HARD-GATE>

Explore project context — files, docs, recent commits.
Ask clarifying questions — one per message, each carrying your own recommended answer so the user can confirm rather than compose. Retrieve facts yourself; ask only about the user's decisions.
Propose 2-3 approaches — with trade-offs; lead with your recommendation and why.
Present the design in sections — each scaled to its complexity, approval after each.
Coverage check — before finalizing, ask whether everything is covered, whether a topic is still uncovered, and whether the user wants to go deeper. Repeat until they confirm coverage.
Write the approved design to
```
docs/specs/YYYY-MM-DD-<topic>-design.md
```
.
Spec self-review — placeholders, contradictions, scope, ambiguity; fix inline.
User reviews the written spec — wait; on requested changes, revise and re-run the review.
Terminal state: invoke plan-crafting. Do not invoke another skill from here.

If the request spans several independent subsystems, decompose it first — name the independent pieces, how they relate, and the build order; each sub-project then gets its own spec → plan → implementation cycle. When a design will not converge, work through

references/design-lenses.md

<HARD-GATE> 在C路径中，除非你已提交设计并获得用户批准，否则不得调用任何实现技能、编写任何代码、搭建项目架构或采取任何实现行动。此规则适用于所有走该路径的项目，无论其看似多么简单。 </HARD-GATE>

探索项目上下文——文件、文档、近期提交记录。
提出澄清问题——每条消息一个问题，同时给出你推荐的答案，以便用户只需确认而非撰写回答。自行获取事实信息；仅询问用户的决策。
提出2-3种实现方案——说明各方案的权衡；优先给出你的推荐方案及理由。
分章节呈现设计——根据复杂度调整篇幅，每章获得批准后再进行下一章。
覆盖范围检查——最终确定前，询问是否所有内容都已覆盖、是否仍有未涉及的主题，以及用户是否需要深入探讨。重复此步骤直到用户确认覆盖完整。
将获批的设计写入
```
docs/specs/YYYY-MM-DD-<topic>-design.md
```
。
规格自我审查——检查占位符、矛盾、范围、模糊性；直接修正。
用户审阅书面规格——等待反馈；根据要求修改并重新提交审阅。
最终状态：调用
```
plan-crafting
```
。从此处不得调用其他技能。

如果需求涉及多个独立子系统，先进行分解——列出独立模块、模块间关系及构建顺序；每个子项目各自遵循规格→计划→实现的周期。如果设计无法达成共识，参考

references/design-lenses.md

。

When NOT to Use

不适用场景

Purely informational requests ("how does X work?", "explain this file").
Running tests or builds, and other read-only inspection with no change requested.
Continuing work whose design was already approved in this conversation — resume it, don't reclassify.

纯信息类请求（如"X如何工作？"、"解释这个文件"）。
运行测试或构建，以及其他无变更请求的只读检查操作。
继续已在本次对话中获批设计的工作——直接恢复，无需重新分类。

Common Rationalizations

常见合理化借口

Rationalization	Reality
"The user said 'just do it', so no design is needed"	That waives the process, not the risk. Name the decision you're taking on yourself in one line, then proceed.
"It's only a config change"	A config change with one deterministic outcome is Route A. A config change that alters product behavior users will notice is Route C.
"It's just a rename, it touches many files but it's mechanical"	Correct — file count is not a criterion in either direction. Check for an unresolved contract decision instead.
"I'll clarify the ambiguity while implementing"	Discovery during implementation is rework, and the user already paid for the wrong direction.
"I can infer what they'd want here"	If you're inferring product behavior the user never stated, that's Route C by definition.
"The spec would only be two lines, so it's not worth writing"	Then write the two lines (Route B). Cheap artifacts are not the same as no artifact.
"We discussed this earlier, the design is settled"	Settled in this conversation with an explicit target contract is Route A. Remembered from a past session is not.

合理化借口	实际情况
"用户说‘直接做’，所以不需要设计"	这只是跳过流程，而非规避风险。用一句话说明你自行承担的决策，然后再继续。
"只是配置变更"	具有单一确定结果的配置变更属于A路径。会改变用户可见产品行为的配置变更属于C路径。
"只是重命名，涉及很多文件但属于机械操作"	正确——文件数量不是判断标准。应检查是否存在未解决的契约决策。
"我会在实现过程中澄清模糊点"	实现过程中的探索属于返工，用户已经为错误方向付出了成本。
"我可以推断他们想要什么"	如果你在推断用户未明确说明的产品行为，根据定义应走C路径。
"规格只有两行，不值得写"	那就写这两行（B路径）。低成本的文档不等于没有文档。
"我们之前讨论过，设计已经确定"	在本次对话中明确达成目标契约的属于A路径。仅回忆过去会话的内容不算。

Red Flags

警示信号

Classifying without writing an assumption ledger.
Choosing Route A while the ledger still holds an
```
assumed
```
entry about product behavior, or holds any
```
contradicted
```
entry at all.
Asking the user a question whose answer is sitting in the repository.
Asking a question without offering your own recommended answer.
Reaching
```
plan-crafting
```
in Route C without an approved spec.
Silently downgrading from Route C to Route A part-way through the work.

未编写前提条件记录就进行分类。
当前提条件记录中仍有关于产品行为的
```
assumed
```
条目，或存在任何
```
contradicted
```
条目时选择A路径。
询问用户仓库中已有的信息。
提出问题时未给出推荐答案。
C路径中未获得获批规格就调用
```
plan-crafting
```
。
在工作过程中悄悄从C路径降级到A路径。

Verification

验证标准

The route was announced explicitly, with the target contract repeated, and a ledger was written.
Every
```
assumed
```
entry that influenced a decision was verified or raised with the user.
Route A stated the repeated target contract and the done criterion; Route C ended with an approved spec and a handoff to
```
plan-crafting
```
.
Scope was never widened silently.

已明确宣布所选路径，复述了目标契约，并编写了前提条件记录。
所有影响决策的
```
assumed
```
条目均已验证或向用户提出。
A路径明确复述了目标契约和完成标准；C路径最终获得了获批规格并移交至
```
plan-crafting
```
。
从未悄悄扩大范围。

Reference Files

参考文件

```
references/design-lenses.md
```
— six lenses for Route C, for when a design will not converge.
```
references/attribution.md
```
— fork source, license, and modifications relative to upstream.

```
references/design-lenses.md
```
——C路径的六个视角，用于设计无法达成共识时。
```
references/attribution.md
```
——分叉来源、许可证及相对于上游的修改内容。