depth-check

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

depth-check

Operationalizes "up to the level the work at hand demands": given a task, figure out what that level actually is — then subtract what the user already knows. The output is a short, honest prep list, not a lecture on the whole codebase.

Not every part of a task deserves deep understanding. Modifying logic demands a working model; calling an interface demands its contract; adjacent code demands awareness that it exists. Grading this is the skill's core move — over-demanding depth is as much a failure as under-demanding it.

将“理解到当前工作所要求的程度”这一原则落地：面对一项任务，先确定其实际需要的理解层级，再扣除用户已经掌握的部分。输出是一份简短、诚实的准备清单，而不是对整个代码库的长篇讲解。

并非任务的每个部分都值得深入理解。修改逻辑需要 Working model；调用接口需要 Contract；相邻代码需要 Awareness。这种分级正是该 skill 的核心动作——要求过深与要求过浅一样，都算失败。

Steps

1. Pin down the task

1. 明确任务

What is actually being changed? If the user's description is vague, sharpen it against the code first ("fix the sync bug" → which sync path, roughly which modules).

实际要改什么？如果用户描述含糊，先结合代码将其收敛（“修复同步 bug”→具体是哪条同步路径、大致涉及哪些模块）。

2. Map the blast radius

2. 梳理 blast radius

Proportionally to the task's size, find:

Files/modules the change will touch directly
Their consumers — who calls this, who depends on its behavior
Invariants in play: assumptions the surrounding code makes, protocol/ordering constraints, things a comment or assertion warns about
Tests covering the area (their existence and shape tell you what behavior is load-bearing)

根据任务规模，按比例找出：

将被直接改动的文件/模块
它们的调用方（consumers）——谁调用它、谁依赖它的行为
涉及的约束（invariants）——周边代码依赖的假设、协议/顺序限制，以及注释或断言所警示的事项
覆盖该区域的测试（tests）——它们是否存在、采用什么形式，能够告诉你哪些行为至关重要（load-bearing）

3. Grade the depth each area demands

3. 评估各部分所需的深度

For each part of the radius, assign the level the work requires:

Working model — you will change its logic: must be able to predict behavior under edge cases
Contract — you will call or depend on it: must know its interface, guarantees, and failure modes
Awareness — it's nearby: must know it exists and when it becomes relevant

为 blast radius 中的每一部分指定工作所要求的层级：

Working model — 你将修改其逻辑：必须能够在 edge cases 下预测行为
Contract — 你将调用它或依赖它：必须了解其 interface、guarantees 和 failure modes
Awareness — 它就在附近：必须知道它存在，以及何时会与之相关

4. Subtract what the user already knows

4. 扣除用户已经掌握的内容

Signals, in order of reliability:

The user's dossier and journal, if they run this pack's session loop — trust it, but flag entries that recent commits may have staled.
The user's own commit history in the area:
```
git log --author=<user email from git config> --oneline -- <path>
```
. Code the user wrote or recently modified is likely understood; code they've never touched likely isn't.
When neither is conclusive, ask directly — one short calibration question ("have you worked in the retry layer before?") beats a wrong assumption.

按可靠性从高到低判断：

用户的 dossier 和 journal（如果他们运行此 pack 的 session loop）——信任这些内容，但标出可能因近期 commits 而过时的条目。
用户在该领域的 commit history：
```
git log --author=<user email from git config> --oneline -- <path>
```
。用户编写或近期修改过的代码很可能已经理解；从未接触过的代码则很可能没有理解。
如果两者都不能得出结论，直接询问——一个简短的校准问题（“你以前做过 retry layer 吗？”）胜过错误假设。

5. Emit the prep list

5. 输出准备清单

Two lists, short:

You already have this — areas where the user's known level meets the demanded level. No homework for these.
Learn first — each entry as a concrete question to answer before coding, not a topic to study: "what guarantees writes are ordered here?" beats "understand the write path". Point at the fastest way to answer each — a specific file to read, a test to run, a
```
why
```
dig into the decision's history.

If the whole list is empty, say so in one line and get out of the way — a task inside known territory needs no ceremony.

For session-loop users: questions that stay open after prep are worth a journal line so they resurface next visit. Skip for everyone else.

两份简短清单：

You already have this（你已经掌握）——用户已知水平达到要求层级的领域。这些部分无需额外作业。
Learn first（先学习）——每一项都写成编码前必须回答的具体问题，而不是一个需要钻研的主题：“这里由什么保证写入顺序？”胜过“理解 write path”。同时指出回答每个问题的最快方式：阅读特定文件、运行某项测试，或通过
```
why
```
追溯该决策的历史。

如果整份清单为空，用一句话说明并立即结束——处于已知领域内的任务不需要这些仪式。

对于使用 session loop 的用户：准备阶段后仍未解决的问题，值得写入 journal 一行，以便下次访问时再次出现。其他用户则跳过。

Guardrails

The prep list must be answerable in minutes-to-an-hour, not a reading program. If it grows past ~5 items, the task is probably too big — say that instead.
Grade honestly in both directions: don't demand a working model of code the task merely calls, and don't wave through logic changes on contract-level knowledge.
Read-only: this skill investigates and reports; it changes nothing in the target project.

准备清单中的问题应能在几分钟到一小时内回答，而不是一套阅读课程。如果超过约 5 项，任务很可能太大——直接说明这一点。
双向诚实评估：不要对仅需调用的代码要求 Working model，也不要仅凭 Contract 层面的理解就放过逻辑改动。
Read-only：该 skill 只负责调查和报告；不会对目标项目做任何更改。