treat-blockers-as-incidents

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Treat Blockers as Incidents

将阻塞视为事件

Core principle. The stone in your shoe is not the walk. It is an incident with a cause, a cost, and a record.

The failure is about your task, or it is not. That single question routes everything below.
The weight sits in Bound it before you start and What you may claim. Everything else spends what those two allow.
You opened this in the middle of something. This is how to get back to that work, not a replacement for it. Name what you were doing before you start, and return to it when this is done.

核心原则。你鞋里的石头不是行走本身的问题，而是一个有起因、有成本、需记录的事件。

故障要么与你的任务相关，要么无关。这一个问题决定了后续所有操作方向。
关键在于「开始前限定范围」和「可做出的声明」。其他所有操作都基于这两部分的设定展开。
你是在某项工作中途遇到的阻塞。本文档指导你如何回到原工作，而非替代原工作。开始排查前先明确你之前在做什么，排查完成后立即回归原任务。

Is this yours

是否属于你的任务范畴

Answer before touching anything.

A test failing because the behaviour is missing is your task. That is
```
test-first-by-evidence
```
.
A defect in the code you are changing is your task. That is
```
debugging-by-evidence
```
.
A tool, runtime, credential, network path, or environment that will not do its job is not your task. It is this.
Where you cannot tell, run the same command in a directory the task does not touch. Still broken means it is not yours.

在触碰任何内容前先明确答案。

因功能缺失导致的测试失败属于你的任务。这对应
```
test-first-by-evidence
```
流程。
你正在修改的代码中存在缺陷属于你的任务。这对应
```
debugging-by-evidence
```
流程。
工具、运行时、凭证、网络路径或环境无法正常工作不属于你的任务。这类情况适用本文档。
若无法判断，在与当前任务无关的目录中执行相同命令。如果仍然失败，则说明故障与你的任务无关。

Bound it before you start

开始前限定排查范围

Say the budget out loud, in the report, before the first probe.

Name the ceiling. A number of probes, or a wall-clock span. Without one, "understand it up to a point" has no point.
Say what reaching the ceiling means. Hand back what you have, incomplete, rather than continue.
Investigate in a session that is not this one where the harness allows it. Context spent here is context the original task no longer has.
Record as you go, not at the end. An investigation that runs out of room produces nothing, and it was the one with the most to teach.

在首次探查前，在报告中明确说出你的排查预算。

设定上限。可以是探查次数，也可以是时间跨度。没有上限的话，「了解到一定程度」就没有明确的标准。
说明达到上限后的处理方式。提交已有的排查结果（即使不完整），而非继续排查。
若工具链允许，在当前会话之外的独立会话中进行排查。在此处消耗的上下文会导致原任务丢失相关上下文。
边排查边记录，不要等到最后。超出范围的排查如果没有记录，就无法留下任何有价值的经验。

Say which state you are in

明确当前所处状态

Report it every time. Each state licenses only what it names.

State	Means	Licenses
`BLOCKED`	a command failed for a reason that is not the task	one reproduction, and reading
`CHARACTERISED`	the failure reproduces and its trigger is named	probes, documentation, source
`EXPLAINED`	the mechanism is observed, not inferred	proposing a fix
`CLEARED`	the fix is applied and the original command runs	returning to the task
`HANDED BACK`	the ceiling was reached, or the fix is not trivial	nothing further without a decision

No state is reached by assumption. Each names an observation you made.
CLEARED
requires the original command to run, not a substitute you found instead.

每次都要报告状态。每个状态仅允许其指定的操作。

状态	含义	允许操作
`BLOCKED`	命令因非任务本身的原因失败	一次复现，以及查阅资料
`CHARACTERISED`	故障可复现且已明确触发条件	探查、查阅文档、查看源码
`EXPLAINED`	已观察到故障机制，而非推断	提出修复方案
`CLEARED`	修复已应用且原命令可正常运行	返回原任务
`HANDED BACK`	已达排查上限，或修复方案不简单	未经决策不得进一步操作

任何状态都不能通过假设达成。每个状态都对应你实际观察到的结果。
CLEARED
状态要求原命令可正常运行，而非你找到的替代方案能运行。

Which rules to read

应查阅哪些规则文档

This table is a gate, not a checklist. Match the left column against what failed.

Read every row whose signal is present. Report an absent one as not-applicable, naming the signal.
A blocker that hides a second blocker matches two rows. Read both.

If you see...	Read
a workaround forming: a flag nobody documents, a copied file, a pinned version chosen to make an error go away	`rules/workarounds-are-findings.md`
the same command failing again, or a fix that made the error move rather than go	`rules/stop-conditions.md`
a non-zero exit from a command that does several things, or an unrelated tool named in the output	`rules/whose-failure-is-it.md`
the first blocker cleared and something new failing right behind it	`rules/the-second-blocker.md`
anything about to be deleted, reset, reinstalled, or rotated to make a command pass	`rules/never-destroy-to-proceed.md`
enough understood to be worth keeping, or a ceiling reached	`rules/record-the-learning.md`

Default stance.

Reproduce once, name the trigger, then stop and decide whether this is worth a bounded investigation or a handback now.
Prefer the primary source over another attempt. The tool's own documentation and its source answer what a fifth retry will not.
Hand back anything whose fix is not obviously clean. The decision is the developer's, and an unclean fix bought quietly is worse than a blocker reported loudly.

本表是筛选规则的入口，而非检查清单。将左列内容与故障现象匹配。

所有符合信号特征的行都要查阅。若某行信号不适用，需在报告中说明该信号。
若一个阻塞背后隐藏着第二个阻塞，则匹配两行。需同时查阅对应的两个文档。

若你发现...	查阅文档
临时方案正在形成：无人文档记录的参数、复制的文件、为消除错误而固定的版本	`rules/workarounds-are-findings.md`
同一命令再次失败，或修复仅让错误转移而非消失	`rules/stop-conditions.md`
执行多步操作的命令返回非零退出码，或输出中提及无关工具	`rules/whose-failure-is-it.md`
第一个阻塞已解决，但紧接着出现新的阻塞	`rules/the-second-blocker.md`
为让命令通过，正准备删除、重置、重新安装或轮换某些内容	`rules/never-destroy-to-proceed.md`
已掌握足够值得留存的信息，或已达排查上限	`rules/record-the-learning.md`

默认原则

复现一次，明确触发条件，然后停止并决策：判断是否值得进行限定范围的排查，或是立即提交排查结果。
优先查阅官方来源而非重复尝试。工具自身的文档和源码能回答的问题，第五次重试也无法解决。
任何修复方案不清晰的问题都要提交反馈。决策应由开发者做出，悄悄采用不严谨的修复方案比大声报告阻塞更糟糕。

What you may claim

可做出的声明类型

Four words, and each one names how you know.

Confirmed. Observed directly, with the command and its output quoted.
Inference. Reasoned from something Confirmed, and labelled so.
Gap. Not established. State the next concrete observation that would close it.
Recommendation. Never proof.
A workaround is a Recommendation until the mechanism is Confirmed. Reporting it as a fix is the failure this skill exists to prevent.
Never claim a command succeeded unless its output was observed.

四种类型，每种都需说明依据。

已确认：直接观察到的结果，需引用命令及其输出。
推断：基于已确认的结果推理得出，需明确标注为推断。
空白：尚未确认的内容。说明能填补空白的下一个具体观察方向。
建议：绝非定论。
临时方案在故障机制被确认前仅属于建议。将其报告为修复方案正是本文档要避免的错误。
除非观察到命令输出，否则绝不能声称命令执行成功。

Where the record goes

记录的存放位置

Use the location the request named, if it named one.
Otherwise the one the instruction file declares.
Otherwise a learnings directory that already exists, in this repository or in the user's agent directory. Writing beside an existing one beats starting a second.
Otherwise decide from the finding. A blocker anyone cloning this repository would hit is written inside it; one only this machine has is written to a learnings directory beside the user's own instruction file, outside any repository.
Where you cannot tell, write outside the repository. A note in the wrong home directory is invisible to everyone; a note committed uninvited is not.
Report the path you chose and whether it is tracked. A wrong guess then costs one line to correct.

若请求中指定了位置，使用该位置。
否则使用指令文件中声明的位置。
否则使用已存在的学习记录目录：可以是当前仓库内的目录，也可以是用户的agent目录。在已有目录旁添加内容优于新建第二个目录。
否则根据发现的内容决定：任何克隆该仓库的人都会遇到的阻塞，记录应放在仓库内；仅当前机器存在的阻塞，记录应放在用户自身指令文件旁的学习记录目录中，且不包含在任何仓库内。
若无法判断，将记录放在仓库外。放在错误的主目录中的记录对所有人都不可见；而未经许可提交到仓库的记录则会带来干扰。
报告你选择的路径及是否被版本跟踪。错误的选择只需一行内容即可修正。

Do not skip this when

以下情况绝不能跳过此流程

The workaround already worked. It worked once, on your machine, for reasons nobody wrote down.
The blocker looks trivial. The ones that eat an afternoon all looked trivial at the first attempt.
You are nearly done. Nearly done is where the second blocker lives.

临时方案已经生效。它仅在你的机器上生效过一次，且原因无人记录。
阻塞看起来微不足道。那些消耗一下午时间的阻塞，最初看起来都微不足道。
你几乎完成任务了。即将完成时正是第二个阻塞容易出现的阶段。

Routing

流程路由

The table above selects the rule. Read a selected rule in full, and say which one you opened.
A defect in the code under change belongs to
debugging-by-evidence
.
Judging a change that already exists belongs to
evidence-backed-review
.
A direct instruction from the user outranks anything here.

根据上表选择对应的规则文档。完整阅读所选规则，并说明你打开了哪一个文档。
正在修改的代码中存在缺陷属于
debugging-by-evidence
流程。
评估已存在的变更属于
evidence-backed-review
流程。
用户的直接指令优先级高于本文档所有内容。