ask-why

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ASK-WHY: Structured Question Investigation

ASK-WHY：结构化问题调查

Mode: read-only on the project. Read files, run read-only commands, and answer. Do not edit, create, commit, push, or comment on anything in the project or its remote. (If the user or a harness asks you to save the answer to a file outside the project, that is fine.)

Standards:

Evidence first. Every claim points to something checkable: a
```
file:line
```
, a commit hash, a CI run ID and log line, a test name, an ADR.
Symptom is not cause. Keep asking why until you reach something a person could change.
Name uncertainty. Say "likely" or "unknown" instead of guessing silently, and say what evidence would settle it.
Falsifiable conclusions. Phrase the answer so the reader can verify or disprove it.

模式：对项目执行只读操作。读取文件、运行只读命令并作答。不得在项目或其远程仓库中编辑、创建、提交、推送或评论任何内容。（如果用户或执行框架要求将答案保存到项目之外的文件，则可以。）

标准：

证据优先。 每项结论都应指向可核查的内容：
```
file:line
```
、commit hash、CI run ID 和日志行、测试名称或 ADR。
症状不等于原因。 持续追问“为什么”，直到找到人们能够采取行动的原因。
明确不确定性。 使用“可能”或“未知”，不要默默猜测，并说明哪些证据能够最终确认结论。
可证伪的结论。 应以读者能够验证或推翻结论的方式表述答案。

Step 1: Classify and check the premise

第 1 步：分类并核查前提

Signal words	Question type	Method
why, why is, why did, what broke, root cause	Causal	Five Whys
where, where should, where does, belongs	Placement	Placement analysis
how, how does, how should	Mechanism	Structured explanation
what, what is, what causes	Definition / discovery	Evidence-based description
which, which is better, which should	Decision / trade-off	Decision matrix

A question can be mixed ("why did this break and where should the guard go"). Answer the main question with its method and handle the rest in Next Steps.

Then check the premise. Questions often carry facts that are wrong or incomplete: the wrong date, the wrong file, "it got fixed" when it did not, "it started failing on Tuesday" when it had failed for weeks, candidates that leave out the obvious home. Verify each stated fact against evidence while you investigate. Report the result in the Premise check line of the output; correcting a false premise is often the most useful part of the answer.

信号词	问题类型	方法
why、why is、why did、what broke、root cause	因果类	Five Whys
where、where should、where does、belongs	位置类	位置分析
how、how does、how should	机制类	结构化说明
what、what is、what causes	定义／发现类	基于证据的描述
which、which is better、which should	决策／权衡类	决策矩阵

一个问题可能包含多种类型（“为什么它被破坏了，保护逻辑应该放在哪里？”）。使用对应方法回答主要问题，并在后续步骤中处理其余部分。

然后核查前提。问题中经常包含错误或不完整的事实：日期有误、文件有误、“已经修复”但实际并未修复、“从周二开始失败”但实际已经失败数周，或者候选方案遗漏了显而易见的归属位置。调查时，应根据证据验证每一项陈述事实。在输出的前提核查一行中报告结果；更正错误前提往往是最有价值的答案部分。

Step 2: Gather evidence

第 2 步：收集证据

Look before you reason. The user rarely pastes the logs, so go get them. Pick the sources that fit the question; you do not need all of them.

Source	Read-only commands	Good for
Git history	`git log --oneline -- <path>` , `git log -S '<string>'` , `git log -L <start>,<end>:<file>` , `git blame -L <range> <file>` , `git show <sha> [--stat] [-- <path>]`	When something changed, who changed what, the fixing commit, the breaking commit
CI runs	`gh run list --workflow <file> --limit 20` , `gh run view <id>` , `gh run view <id> --log-failed`	Exact error text, onset (first failing run), whether the fix has run green since
Issues and PRs	`gh pr view <n>` , `gh issue view <n>` , `gh pr list --search <sha>`	Intent behind a change, discussion of the failure
Tests	Read the tests that cover the code; run them only if they are side-effect free	Whether the behaviour is pinned, whether a regression guard exists
Decisions and docs	ADRs ( `docs/adr*` , `docs/decisions` ), README, CONTRIBUTING, architecture notes	Intended design, ownership, rules the answer must respect
Runtime config	CI workflow YAML, Makefiles, scripts, package manifests	Who calls what, with which arguments

In long CI logs, find the first failing step and its first error line; later errors are often knock-on effects of the early exit, so name them as such rather than as separate causes.

For a causal question about something that "got fixed", find both ends: the fixing commit, and the breaking change plus the first failing run. The span between them often explains why nobody noticed (a weekly-only job, a second failure masking the first).

Keep a short list of what you checked and what you could not reach (no

gh

auth, logs expired, no network, file outside the repo). It goes in the Evidence checked section, so the reader knows how far to trust the answer.

先观察，再推理。用户很少直接粘贴日志，因此应主动获取。根据问题选择合适的证据来源，无需全部使用。

来源	只读命令	适用场景
Git 历史	`git log --oneline -- <path>` 、 `git log -S '<string>'` 、 `git log -L <start>,<end>:<file>` 、 `git blame -L <range> <file>` 、 `git show <sha> [--stat] [-- <path>]`	某项内容何时发生变化、谁改了什么、修复 commit、引入问题的 commit
CI 运行	`gh run list --workflow <file> --limit 20` 、 `gh run view <id>` 、 `gh run view <id> --log-failed`	确切的错误文本、问题开始时间（首次失败的运行）、修复后的运行是否一直为绿色
Issue 和 PR	`gh pr view <n>` 、 `gh issue view <n>` 、 `gh pr list --search <sha>`	变更背后的意图、对故障的讨论
测试	阅读覆盖相关代码的测试；仅在测试没有副作用时运行	行为是否已被固定、是否存在回归防护
决策和文档	ADR（ `docs/adr*` 、 `docs/decisions` ）、README、CONTRIBUTING、架构说明	预期设计、职责归属、答案必须遵守的规则
运行时配置	CI workflow YAML、Makefile、脚本、package manifest	谁调用什么，以及使用哪些参数调用

对于冗长的 CI 日志，应找到第一个失败步骤及其第一条错误信息。后续错误通常是过早退出引发的连锁效应，应将其说明为此类影响，而不是分别视为独立原因。

对于“已经修复”的因果问题，应同时找到两端：修复 commit，以及引入问题的变更和首次失败的运行。两者之间的时间跨度通常能够解释为什么问题没有及时被发现，例如任务每周才运行一次，或第二个失败掩盖了第一个失败。

应保留一份简短的已核查内容和无法获取内容的清单，例如没有

gh

身份验证、日志已过期、没有网络、文件位于仓库之外。该清单应放入已核查证据部分，让读者了解答案的可信程度。

Step 3: Apply the method

第 3 步：应用方法

Method 1: Five Whys (causal)

方法 1：Five Whys（因果类）

State the symptom: what fails, when, under what conditions, expected vs actual, and the exact error text.

Then build a WHY tree. Follow each branch until you reach a cause that someone can act on (a decision, a missing guard, a contract nobody owns). That is usually 3 to 5 levels. Stop a branch early if the evidence ends there, and do not pad a branch to reach five. Open a second branch only for a separate symptom or a contributing cause, such as an earlier failure that hid this one.

PROBLEM: [falsifiable problem statement, with corrected facts if the premise was wrong]

WHY 1A: [first observable cause]     [Evidence: ...]
  WHY 2A: [why 1A happened]          [Evidence: ...]
    ...                              (as many levels as the evidence supports)
    -> ROOT CAUSE A: [one sentence]
    -> IMPLICATION A: [what this means for a fix or a guard]

WHY 1B: [separate or contributing cause, if any]
  ...

CROSS-VALIDATION:
- Every symptom explained: [yes / partial: gaps]
- Timeline consistent (cause precedes onset, fix precedes recovery): [yes / no / unverified]

陈述症状：什么失败了、何时失败、在什么条件下失败、预期与实际情况分别是什么，以及确切的错误文本。

然后构建 WHY 树。沿着每个分支持续追问，直到找到人们能够采取行动的原因（一个决策、一项缺失的防护，或一份无人负责的契约）。通常需要 3 到 5 层。如果证据在某处终止，应提前结束该分支，不要为了凑足五层而添加内容。只有在存在独立症状或促成原因时，才开启第二个分支，例如更早发生的失败掩盖了当前失败。

问题：[可证伪的问题陈述；如果前提有误，则使用更正后的事实]

WHY 1A：[第一个可观察原因]     [证据：...]
  WHY 2A：[WHY 1A 发生的原因]    [证据：...]
    ...                          （根据证据支持的程度继续展开）
    -> 根因 A：[一句话]
    -> 影响 A：[这对修复或防护意味着什么]

WHY 1B：[独立原因或促成原因（如有）]
...

交叉验证：
- 每个症状均已解释：[是 / 部分：存在缺口]
- 时间线一致（原因早于问题出现，修复早于恢复）：[是 / 否 / 未验证]

Method 2: Placement analysis (where)

方法 2：位置分析（where）

Works for any kind of home: a function's module, a check's script, a package, a layer, a service, a CI job, or a bounded context.

Characterise the thing being placed: what it does, what it reads or owns, what triggers it to change, and what it depends on.

List the candidates. Use the user's list, and add an obvious candidate they missed if the evidence points to one (say you added it). Separate a home (where the code or rule lives) from wiring (where it is invoked, such as a CI job that only calls a script). If a candidate is wiring, say so: the answer may be "lives in A, runs from B". Still score a wiring-only candidate, judging it by where its logic would have to go (inline YAML, a new script), so the table compares like with like.

Score each candidate from 1 to 5 (higher is better), citing evidence for each score:

Criterion	Question
Responsibility fit	Does this home already describe itself as doing this kind of thing (its header, README, ADR, naming)?
Dependency direction	Does placing it here keep dependencies pointing the way they already point (tests depend on code, not code on tests; shipped code not on repo-only files)?
Existing analogues	Does this home already hold similar things you could copy the pattern from?
Wiring cost	How much new plumbing is needed: new jobs, CLI verbs, imports, duplicated discovery logic? Less is better.
Change alignment	Does it change for the same reasons and get maintained by the same people as this home?

Total the five scores (out of 25) unweighted, unless the user named a priority; then say which criterion you weighted and why. If the top two are within 2 points, treat it as a tie and decide on the criterion that matters most for this case, defaulting to lower wiring cost, then to the stronger existing analogue. Name the deciding criterion either way.

State the recommendation, the main risk, and anything that would change it.

适用于任何类型的归属位置：函数的 module、检查的 script、package、layer、service、CI job 或 bounded context。

描述待定位对象：它做什么、读取或拥有什么、什么变化会触发它，以及它依赖什么。

列出候选项。 使用用户提供的列表；如果证据指向一个被遗漏的明显候选项，则将其补充进来，并说明已添加该候选项。应区分归属位置（代码或规则存放在哪里）与接线位置（从何处调用，例如仅调用脚本的 CI job）。如果候选项只是接线位置，应明确说明；答案可能是“逻辑存放在 A，从 B 运行”。仍然要给仅作为接线位置的候选项评分，依据其逻辑最终应放置的位置进行判断，例如内联 YAML 或新脚本，从而保证表格中的候选项具有可比性。

对每个候选项按 1 到 5 分评分（分数越高越好），并为每项评分引用证据：

标准	问题
职责契合度	该位置是否已通过其 header、README、ADR 或命名明确定位为负责此类事项？
依赖方向	放在这里是否能保持现有依赖方向（测试依赖代码，而不是代码依赖测试；发布代码不依赖仅存在于仓库中的文件）？
现有类似案例	该位置是否已经包含可复用模式的类似内容？
接线成本	需要多少新的连接工作，例如新 job、CLI verb、import 或重复的发现逻辑？成本越低越好。
变更一致性	它是否会因为与当前位置相同的原因发生变化，并由同一批人员维护？

将五项分数相加得出总分（满分 25），默认不加权；除非用户明确指定了优先级，否则不进行加权。如果用户指定了优先级，应说明对哪项标准进行了加权以及原因。如果前两名相差不超过 2 分，则视为并列，并选择本案例中最重要的标准作出决定；默认优先考虑更低的接线成本，其次是更明确的现有类似案例。无论采用哪种方式，都应指出最终决定性标准。

应给出推荐方案、主要风险，以及哪些情况会改变该推荐。

Method 3: Structured explanation (how)

方法 3：结构化说明（how）

Mechanism: the steps and components involved, with
```
file:line
```
for each.
Key invariants: what must hold for it to work.
Failure modes: when it breaks and why.
Diagram if it helps: ASCII or Mermaid.

机制：列出涉及的步骤和组件，并为每项提供
```
file:line
```
。
关键不变量：说明其正常工作必须满足的条件。
故障模式：说明何时以及为什么会发生故障。
图示：如果有助于理解，可使用 ASCII 或 Mermaid。

Method 4: Evidence-based description (what)

方法 4：基于证据的描述（what）

Definition: one sentence.
Scope: what it includes and excludes.
Evidence: where it is observable in code, config, or docs.
Common confusions: what it gets mistaken for.

定义：用一句话说明。
范围：说明包含和不包含的内容。
证据：指出可以在代码、配置或文档中观察到的位置。
常见混淆：说明它经常被误认为什么。

Method 5: Decision matrix (which)

方法 5：决策矩阵（which）

Option	Pros	Cons	Fit (1-5)

State the winner and the deciding criterion.

方案	优点	缺点	契合度（1-5）

应指出获胜方案及其决定性标准。

Output format

输出格式

undefined

undefined

Question

问题

[the question as asked] Premise check: [confirmed | corrected: what was wrong and the evidence | unverifiable: why] (list each stated fact separately if they differ)

[用户提出的问题] 前提核查： [已确认 | 已更正：哪里有误以及相关证据 | 无法验证：原因]（如果各项事实不同，则逐项列出）

Classification

分类

[question type] → [method]

[问题类型] → [方法]

Evidence checked

已核查证据

[source]: [what you looked at, e.g.
```
git log -- scripts/x.sh
```
, run 123 --log-failed]
Not reachable: [source and reason, or "none"]

[来源]：[查看了什么，例如
```
git log -- scripts/x.sh
```
、run 123 --log-failed]
无法获取：[来源及原因，或“无”]

Investigation

调查

[method output: WHY tree, placement table, explanation, etc.]

[方法输出：WHY 树、位置表格、说明等]

Answer

答案

[2-5 sentences, written once: the direct answer, the key evidence behind it, and your confidence. Do not repeat it elsewhere as a summary.]

[用 2 到 5 句话一次性写出：直接答案、背后的关键证据以及置信度。不要在其他位置再次以摘要形式重复。]

Next Steps (optional)

后续步骤（可选）

[up to 3 bullets, routed as below]

undefined

[最多 3 个要点，按以下方式路由]

undefined

Routing next steps

后续步骤的路由方式

This skill stops at the answer. Point to the right follow-up instead of fixing anything:

Finding	Next step
Open bug	Suggest `/nw-bugfix` with the root cause
Bug already fixed	Name the fixing commit or PR. Say whether a run since the fix proves it (cite the run) or not yet. If no test or check would catch a repeat, suggest a regression guard and where it belongs
Design gap or missing guard	Suggest `/nw-design` , or name the small change and where it goes
Stale or wrong docs	Name the `file:line` and what it should say
Missing test coverage	Name the behaviour and the test file that should hold it
Nothing actionable	Omit Next Steps

此 skill 的职责止于给出答案。应指向正确的后续流程，而不是直接修复问题：

发现	后续步骤
尚未修复的 bug	建议使用 `/nw-bugfix` ，并提供根因
已修复的 bug	指明修复 commit 或 PR。说明修复后的运行是否能够证明问题已解决（引用该运行），还是尚不能证明。如果没有测试或检查能够捕获问题再次发生，建议添加回归防护，并说明其归属位置
设计缺口或缺失的防护	建议使用 `/nw-design` ，或指出需要进行的小型变更及其放置位置
文档过时或有误	指明 `file:line` 以及文档应如何修改
测试覆盖缺失	说明应被测试覆盖的行为以及应承载该测试的测试文件
没有任何可执行事项	省略后续步骤

Examples

示例

```
/ask-why "Why did the nightly deploy start failing last week?"
```
: causal. Pulls
```
gh run list
```
for the workflow to find the first failing run, reads its
```
--log-failed
```
, uses
```
git log
```
between the last green and first red run to find the breaking change, and may correct "last week" if failures began earlier.
```
/ask-why "Where should the retry policy live: the HTTP client wrapper or each service caller?"
```
: placement. Characterises the policy, scores both candidates on the five criteria with evidence, and recommends one with the deciding criterion named.
```
/ask-why "How does the token refresh cycle work here?"
```
: mechanism. Steps with
```
file:line
```
, invariants, failure modes, and a sequence diagram.

```
/ask-why "Why did the nightly deploy start failing last week?"
```
：因果类。运行
```
gh run list
```
查找 workflow 的首次失败运行，读取其
```
--log-failed
```
，使用
```
git log
```
检查最后一次绿色运行与首次红色运行之间的变更以定位引入问题的变更；如果失败实际开始得更早，还可能更正“last week”这一前提。
```
/ask-why "Where should the retry policy live: the HTTP client wrapper or each service caller?"
```
：位置类。描述该策略，根据五项标准并结合证据对两个候选项评分，给出推荐方案并指出决定性标准。
```
/ask-why "How does the token refresh cycle work here?"
```
：机制类。列出带有
```
file:line
```
的步骤、不变量、故障模式以及时序图。

Constraints

约束

No code generation and no fixes. Describe the change; do not make it.
No project writes or outward actions. No edits, commits, pushes, issue or PR comments, or workflow dispatches.
Cite sources. Every factual claim references a file and line, commit, CI run, log excerpt, test, or named design principle.

不生成代码，也不修复问题。 描述应进行的变更，但不要实际执行。
不写入项目，也不执行对外操作。 不得编辑、提交、推送、评论 Issue 或 PR，也不得触发 workflow。
引用来源。 每项事实性结论都必须引用文件和行号、commit、CI run、日志摘录、测试或已命名的设计原则。