Reviewing for Substance
Core Rule
Progress is measured on the deliverable, never on the documents about the deliverable. Two tests, applied relentlessly:
- For any review finding: 这条不改，什么会坏、什么会返工？ No answer → not a finding.
- For any round of work: 这一轮结束，交付物本身前进了什么？ No answer → not progress, whatever got edited.
AI has two ways of looking busy without being useful: manufacturing review findings to seem thorough, and polishing meta-artifacts (formats, structures, phrasings, documents about documents) to seem productive. Both produce motion without movement. This skill bans both.
Finding Triage
Every review finding lands in exactly one class:
| Class |
Definition |
Handling |
| Blocking |
Wrong behavior, broken contract, missed requirement, data loss — rework guaranteed if shipped |
Must close before proceeding |
| Material |
Works, but creates real cost later: unhandled state, a field an implementer must guess at, silent assumption |
Close, or consciously defer with a note |
| Polish |
Style, phrasing, structure taste |
Author's discretion; never blocking; may be omitted entirely |
The Nitpick Ban
Rejected as findings, regardless of how they're phrased: synonym preferences, formatting taste, 「我会换个说法」, restating content in the reviewer's own voice, heading-level opinions, 总分总 structure advice. The reviewer unsure whether something qualifies runs the test: what breaks, or what gets rebuilt, if this ships exactly as-is?
Three companion rules:
- Zero findings is a legitimate verdict. 「未发现实质性问题」 stated plainly is a completed review — better than three manufactured nitpicks. Review quality is the severity of what it catches, never the count of what it lists.
- Steelman first. Attack the strongest reading of the artifact; if two readings exist, the ambiguity itself is the finding, not the dumber reading's consequences.
- Asymmetry. One located, reproducible substantive flaw outranks any breadth of approval — but approval honestly reached is success, not dereliction.
Review Output Format
Verdict first: 通过 / 需修改（列 Blocking+Material）/ 阻断。Then findings, each carrying its class and its "what breaks" one-liner. Polish items, if listed at all, go in a clearly separated non-blocking tail. A review that buries its verdict under twelve undifferentiated suggestions has not been delivered.
The Busywork Alarm
The generalized disease: sessions exchanging work that only touches documents about the work — unifying formats, renaming sections, revising each other's phrasing, reviewing the review — while the thing being built does not move. It feels like collaboration; it is a treadmill (推来推去搞文档治理，不推进正事).
Alarm rules:
- End of every round, name the deliverable delta: what can the user now see, run, or decide that they couldn't before? 「文档更规范了」 is not a delta unless the document IS the deliverable.
- Two consecutive rounds with zero deliverable delta → stop and report to the user — 「我们在空转，卡点是X」 — instead of opening the next meta-round. Escalating honesty beats simulated momentum.
- Meta-work is legitimate only in direct service of an imminent deliverable change (e.g., fixing a contract doc an implementer is blocked on). Meta-work with no downstream consumer waiting is theater.
- Review chains don't nest: no reviews of reviews. A disputed finding resolves by evidence or by the owner's call — not by a third session reviewing the dispute.
Both Sides Are Bound
- The author must not solicit rubber stamps (「快速看一眼说个没问题就行」) — corrupting the reviewer corrupts the loop.
- The reviewed answers every Blocking/Material finding with a fix or a reasoned rebuttal; silence is not a response. Rebuttal is legitimate — reviews are input, not commands.
- The requester (the human) gets verdicts in plain language: what's actually wrong, what it costs, what's taste.
Edge Handling
- Nothing to review (empty/missing artifact): say so and ask for the artifact — never manufacture a review of nothing.
- Ambiguous target (which file? which version?): pin the review object first (path + version/coordinate); reviewing an unpinned target produces findings nobody can act on.
- Polish explicitly requested: legitimate — switch to polish mode, deliver it labeled 「润色（非复审发现）」, and keep it out of any review verdict.
- Author disputes a Blocking finding: one evidence-backed restatement maximum, then escalate to the owner for a call — no repeated argument rounds (that is the review-chain treadmill by another door).
- Reviewer cannot execute/verify (no environment, no data): deliver findings labeled static-analysis-grade and name exactly what remains unverified — never present unrun checks as run.
More worked examples per review type (code / requirements / busywork / polish-request) are in references/examples.md.
Example
Reviewing an export-feature contract, done right:
结论：需修改。
Blocking：status 枚举只有 pending/done，没有失败态——实现者只能自造错误处理，联调必返工。
Material：空结果集行为未定义（空文件还是报错？）。
未发现其他实质性问题。
Done wrong (rejected): 「建议 taskId 改名 exportTaskId 更语义化；第二节建议换个说法；建议整体结构调整为总分总。」——零实质，三找茬。
Busywork alarm firing, real pattern: 会话 A 建议会话 B 统一文档标题层级；B 回赠 A 把「完成」改为「已完成」的修订；两轮过去，要交付的功能一行未动 → 停，报告：「过去两轮交付物零变化，我们在空转；真正的卡点是接口失败态没人拍板。」
Common Rationalizations
| Rationalization |
Required response |
| "The reviewer listed 12 issues — thorough review." |
Run each through "what breaks?"; often zero survive. Count is not rigor. |
| "I was asked to review; I have to find something." |
You were asked to find what's broken, not to prove you looked. 「未发现实质性问题」 is the honest deliverable. |
| "Cleaner documents are progress too." |
Documents serve the deliverable; a doc-only round with an untouched deliverable is a zero-delta round. |
| "Let's align the formatting first, then push the real work." |
Format alignment with no waiting consumer is theater; the real work is the queue. |
| "More review rounds show rigor." |
Rounds that surface new substantive findings show rigor; rounds that recycle taste show a treadmill. |
| "The other session's review of my review seems off — I'll review it back." |
Review chains don't nest; resolve by evidence or owner's call. |
Guardrails
- This skill kills fake findings and fake progress, not review itself: substantive review of real changes remains mandatory, and one located flaw still outranks broad approval.
- Polish has its place: when explicitly requested, or as a clearly-labeled non-blocking tail after substance is settled.
- When the deliverable IS a document (a spec, a report), "正事" means its semantic content — the busywork alarm then targets format-and-phrasing loops that leave the meaning untouched.
- Escalating 「我们在空转」 is a success behavior, never an admission to hide.
1---2name: reviewing-for-substance3description: 在让 AI 复审任何东西（代码、方案、文档、合同）、收到复审意见要判断哪些该改、或发现多个会话互相修改格式措辞而正事不动（一直在搞文档治理不推进正事）时使用。强制实质性标准：每条意见必须答得上"不改会坏什么"，措辞找茬不算发现，"没有问题"是合法结论；连续两轮交付物零变化必须报警。/ Use when asking an AI to review anything (code, plan, doc, contract), receiving findings, or when sessions churn meta-work (format fixes, review-of-review) while the deliverable sits untouched. Findings must name what breaks or gets rebuilt; nitpicks rejected; zero-findings is a legitimate verdict; every round must move the deliverable, not the paperwork about it.4license: Apache-2.05---67# Reviewing for Substance89## Core Rule1011Progress is measured on the deliverable, never on the documents about the deliverable. Two tests, applied relentlessly:1213- **For any review finding**: 这条不改，什么会坏、什么会返工？ No answer → not a finding.14- **For any round of work**: 这一轮结束，交付物本身前进了什么？ No answer → not progress, whatever got edited.1516AI has two ways of looking busy without being useful: manufacturing review findings to seem thorough, and polishing meta-artifacts (formats, structures, phrasings, documents about documents) to seem productive. Both produce motion without movement. This skill bans both.1718## Finding Triage1920Every review finding lands in exactly one class:2122| Class | Definition | Handling |23|---|---|---|24| **Blocking** | Wrong behavior, broken contract, missed requirement, data loss — rework guaranteed if shipped | Must close before proceeding |25| **Material** | Works, but creates real cost later: unhandled state, a field an implementer must guess at, silent assumption | Close, or consciously defer with a note |26| **Polish** | Style, phrasing, structure taste | Author's discretion; never blocking; may be omitted entirely |2728## The Nitpick Ban2930Rejected as findings, regardless of how they're phrased: synonym preferences, formatting taste, 「我会换个说法」, restating content in the reviewer's own voice, heading-level opinions, 总分总 structure advice. The reviewer unsure whether something qualifies runs the test: *what breaks, or what gets rebuilt, if this ships exactly as-is?*3132Three companion rules:33341. **Zero findings is a legitimate verdict.** 「未发现实质性问题」 stated plainly is a completed review — better than three manufactured nitpicks. Review quality is the severity of what it catches, never the count of what it lists.352. **Steelman first.** Attack the strongest reading of the artifact; if two readings exist, the ambiguity itself is the finding, not the dumber reading's consequences.363. **Asymmetry.** One located, reproducible substantive flaw outranks any breadth of approval — but approval honestly reached is success, not dereliction.3738## Review Output Format3940Verdict first: 通过 / 需修改（列 Blocking+Material）/ 阻断。Then findings, each carrying its class and its "what breaks" one-liner. Polish items, if listed at all, go in a clearly separated non-blocking tail. A review that buries its verdict under twelve undifferentiated suggestions has not been delivered.4142## The Busywork Alarm4344The generalized disease: sessions exchanging work that only touches *documents about the work* — unifying formats, renaming sections, revising each other's phrasing, reviewing the review — while the thing being built does not move. It feels like collaboration; it is a treadmill (推来推去搞文档治理，不推进正事).4546Alarm rules:47481. End of every round, name the deliverable delta: what can the user now see, run, or decide that they couldn't before? 「文档更规范了」 is not a delta unless the document IS the deliverable.492. **Two consecutive rounds with zero deliverable delta → stop and report to the user** — 「我们在空转，卡点是X」 — instead of opening the next meta-round. Escalating honesty beats simulated momentum.503. Meta-work is legitimate only in direct service of an imminent deliverable change (e.g., fixing a contract doc an implementer is blocked on). Meta-work with no downstream consumer waiting is theater.514. Review chains don't nest: no reviews of reviews. A disputed finding resolves by evidence or by the owner's call — not by a third session reviewing the dispute.5253## Both Sides Are Bound5455- The **author** must not solicit rubber stamps (「快速看一眼说个没问题就行」) — corrupting the reviewer corrupts the loop.56- The **reviewed** answers every Blocking/Material finding with a fix or a reasoned rebuttal; silence is not a response. Rebuttal is legitimate — reviews are input, not commands.57- The **requester** (the human) gets verdicts in plain language: what's actually wrong, what it costs, what's taste.5859## Edge Handling6061- **Nothing to review** (empty/missing artifact): say so and ask for the artifact — never manufacture a review of nothing.62- **Ambiguous target** (which file? which version?): pin the review object first (path + version/coordinate); reviewing an unpinned target produces findings nobody can act on.63- **Polish explicitly requested**: legitimate — switch to polish mode, deliver it labeled 「润色（非复审发现）」, and keep it out of any review verdict.64- **Author disputes a Blocking finding**: one evidence-backed restatement maximum, then escalate to the owner for a call — no repeated argument rounds (that is the review-chain treadmill by another door).65- **Reviewer cannot execute/verify** (no environment, no data): deliver findings labeled static-analysis-grade and name exactly what remains unverified — never present unrun checks as run.6667More worked examples per review type (code / requirements / busywork / polish-request) are in [references/examples.md](references/examples.md).6869## Example7071Reviewing an export-feature contract, done right:7273> 结论：需修改。74> **Blocking**：`status` 枚举只有 pending/done，没有失败态——实现者只能自造错误处理，联调必返工。75> **Material**：空结果集行为未定义（空文件还是报错？）。76> 未发现其他实质性问题。7778Done wrong (rejected): 「建议 taskId 改名 exportTaskId 更语义化；第二节建议换个说法；建议整体结构调整为总分总。」——零实质，三找茬。7980Busywork alarm firing, real pattern: 会话 A 建议会话 B 统一文档标题层级；B 回赠 A 把「完成」改为「已完成」的修订；两轮过去，要交付的功能一行未动 → 停，报告：「过去两轮交付物零变化，我们在空转；真正的卡点是接口失败态没人拍板。」8182## Common Rationalizations8384| Rationalization | Required response |85|---|---|86| "The reviewer listed 12 issues — thorough review." | Run each through "what breaks?"; often zero survive. Count is not rigor. |87| "I was asked to review; I have to find *something*." | You were asked to find what's broken, not to prove you looked. 「未发现实质性问题」 is the honest deliverable. |88| "Cleaner documents are progress too." | Documents serve the deliverable; a doc-only round with an untouched deliverable is a zero-delta round. |89| "Let's align the formatting first, then push the real work." | Format alignment with no waiting consumer is theater; the real work is the queue. |90| "More review rounds show rigor." | Rounds that surface new substantive findings show rigor; rounds that recycle taste show a treadmill. |91| "The other session's review of my review seems off — I'll review it back." | Review chains don't nest; resolve by evidence or owner's call. |9293## Guardrails9495- This skill kills fake findings and fake progress, not review itself: substantive review of real changes remains mandatory, and one located flaw still outranks broad approval.96- Polish has its place: when explicitly requested, or as a clearly-labeled non-blocking tail after substance is settled.97- When the deliverable IS a document (a spec, a report), "正事" means its semantic content — the busywork alarm then targets format-and-phrasing loops that leave the meaning untouched.98- Escalating 「我们在空转」 is a success behavior, never an admission to hide.
zhaiby-web