verification-before-completion

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Verification Before Completion

完成前的验证流程

Overview

概述

Claiming work is complete without verification is dishonesty, not efficiency.

Core principle: Evidence before claims, always.

Violating the letter of this rule is violating the spirit of this rule.

未经验证就宣称工作完成是不诚信的行为，而非高效。

核心原则： 始终先有证据，再做声明。

违反规则的字面要求，即违反规则的精神内核。

The Iron Law

铁律

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

If you haven't run the verification command in this message, you cannot claim it passes.

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

如果未运行此消息中的验证命令，你不得宣称任务已通过。

The Gate Function

把关流程

BEFORE claiming any status or expressing satisfaction:

1. IDENTIFY: What command proves this claim?
2. RUN: Execute the FULL command (fresh, complete)
3. READ: Full output, check exit code, count failures
4. VERIFY: Does output confirm the claim?
   - If NO: State actual status with evidence
   - If YES: State claim WITH evidence
5. REFLECT: Pause to consider tool results before next action
6. ONLY THEN: Make the claim

Skip any step = lying, not verifying

在宣称任何状态或表达满意之前：

1. 明确：用什么命令能证明该声明？
2. 执行：完整运行命令（全新、完整的执行）
3. 读取：查看完整输出，检查退出码，统计失败数量
4. 验证：输出是否能佐证声明？
   - 若不能：附上证据说明实际状态
   - 若能：附上证据做出声明
5. 反思：在下一步行动前，暂停思考工具结果
6. 仅在此时：做出声明

跳过任意步骤 = 未进行验证，属于不实陈述

Common Failures

常见错误

Claim	Requires	Not Sufficient
Tests pass	Test command output: 0 failures	Previous run, "should pass"
Linter clean	Linter output: 0 errors	Partial check, extrapolation
Build succeeds	Build command: exit 0	Linter passing, logs look good
Bug fixed	Test original symptom: passes	Code changed, assumed fixed
Regression test works	Red-green cycle verified	Test passes once
Agent completed	VCS diff shows changes	Agent reports "success"
Requirements met	Line-by-line checklist	Tests passing

声明内容	所需验证	不充分的依据
测试通过	测试命令输出：0个失败用例	之前的运行结果、“应该能通过”
代码检查器无问题	代码检查器输出：0个错误	部分检查、推断结果
构建成功	构建命令：退出码为0	代码检查器通过、日志看起来正常
Bug已修复	针对原问题的测试用例通过	代码已修改、假设已修复
回归测试有效	已验证红-green循环	测试仅通过一次
Agent已完成任务	版本控制系统（VCS）差异显示有变更	Agent报告“成功”
需求已满足	逐条核对检查清单	测试通过

Red Flags - STOP

危险信号 - 立即停止

If you find yourself:

Using "should", "probably", "seems to"
Expressing satisfaction before verification ("Great!", "Perfect!", "Done!", etc.)
About to commit/push/PR without verification
Trusting agent success reports
Relying on partial verification
Thinking "just this once"
Tired and wanting work over
ANY wording implying success without having run verification

STOP. Run verification. Get evidence. THEN speak.

如果你发现自己出现以下情况：

使用“应该”“可能”“看起来”这类表述
在验证前就表达满意（比如“太棒了！”“完美！”“完成了！”等）
未经验证就准备提交/推送/发起PR
信任Agent的成功报告
依赖部分验证结果
想着“就这一次例外”
因疲惫想尽快结束工作
任何未运行验证就暗示成功的表述

立即停止。运行验证，获取证据，再进行表述。

Rationalization Prevention

避免自我合理化

Excuse	Reality
"Should work now"	RUN the verification
"I'm confident"	Confidence ≠ evidence
"Just this once"	No exceptions
"Linter passed"	Linter ≠ compiler
"Agent said success"	Verify independently
"I'm tired"	Exhaustion ≠ excuse
"Partial check is enough"	Partial proves nothing
"Different words so rule doesn't apply"	Spirit over letter
"I already tested it manually"	Manual ≠ automated evidence
"The code looks correct"	Looking ≠ running

借口	实际情况
“现在应该能正常运行了”	去运行验证命令
“我很有信心”	信心≠证据
“就这一次例外”	没有例外情况
“代码检查器通过了”	代码检查器≠编译器
“Agent说成功了”	独立进行验证
“我累了”	疲惫不能成为借口
“部分检查就足够了”	部分检查无法证明任何事情
“表述不同，所以规则不适用”	遵循规则精神而非字面表述
“我已经手动测试过了”	手动测试≠自动化证据
“代码看起来是正确的”	看代码≠运行代码

Key Patterns

关键规范示例

Tests:

✅ [Run test command] [See: 34/34 pass] "All tests pass"
❌ "Should pass now" / "Looks correct"

Regression tests (TDD Red-Green):

✅ Write → Run (pass) → Revert fix → Run (MUST FAIL) → Restore → Run (pass)
❌ "I've written a regression test" (without red-green verification)

Build:

✅ [Run build] [See: exit 0] "Build passes"
❌ "Linter passed" (linter doesn't check compilation)

Requirements:

✅ Re-read plan → Create checklist → Verify each → Report gaps or completion
❌ "Tests pass, phase complete"

Agent delegation:

✅ Agent reports success → Check VCS diff → Verify changes → Report actual state
❌ Trust agent report

测试：

✅ [运行测试命令] [结果：34/34通过] “所有测试通过”
❌ “现在应该能通过了” / “看起来是正确的”

回归测试（TDD红-green流程）：

✅ 编写测试 → 运行（失败）→ 还原修复代码 → 运行（必须失败）→ 恢复修复代码 → 运行（通过）
❌ “我已经编写了回归测试”（未验证红-green流程）

构建：

✅ [运行构建命令] [结果：退出码0] “构建通过”
❌ “代码检查器通过了”（代码检查器不检查编译情况）

需求：

✅ 重新阅读计划 → 创建检查清单 → 逐项验证 → 报告差距或完成情况
❌ “测试通过，阶段完成”

Agent委托任务：

✅ Agent报告成功 → 检查VCS差异 → 验证变更 → 报告实际状态
❌ 信任Agent的报告

Why This Matters

为什么这很重要

From real failure patterns:

Your user said "I don't believe you" - trust broken
Undefined functions shipped - would crash in production
Missing requirements shipped - incomplete features
Time wasted on false completion → redirect → rework
Violates: "Honesty is a core value. If you lie, you'll be replaced."

来自真实的失败案例：

用户说“我不相信你”——信任破裂
未定义的函数被发布——会在生产环境崩溃
遗漏需求的功能被发布——功能不完整
因虚假完成浪费时间→重新调整→返工
违反核心价值观：“诚信是核心价值。若你撒谎，将被替换。”

When To Apply

适用场景

ALWAYS before:

ANY variation of success/completion claims
ANY expression of satisfaction
ANY positive statement about work state
Committing, PR creation, task completion
Moving to next task
Delegating to agents

Rule applies to:

Exact phrases
Paraphrases and synonyms
Implications of success
ANY communication suggesting completion/correctness

在以下场景前必须执行：

任何形式的成功/完成声明
任何表达满意的表述
任何关于工作状态的正面陈述
提交、发起PR、标记任务完成
切换到下一个任务
委托任务给Agent

规则适用于：

精确表述
改写和同义词
暗示成功的表述
任何暗示完成/正确性的沟通内容

Self-Critique Gate (BEFORE Verification Commands)

自我审查关卡（运行验证命令前）

MANDATORY: Check these BEFORE running verification commands:

必须执行：在运行验证命令前检查以下内容：

Code Quality

代码质量

Implementation Completeness

实现完整性

Self-Critique Verdict

自我审查结论

PROCEED: [YES/NO] CONFIDENCE: [High/Medium/Low]

If NO → Fix issues before verification
If YES → Proceed to verification commands below

是否继续： [是/否] 信心程度： [高/中/低]

若否 → 先修复问题再进行验证
若是 → 继续运行下方的验证命令

Validation Levels

验证级别

Match validation depth to task complexity:

Level	Name	Commands	When to Use
1	Syntax & Style	`npm run lint` , `tsc --noEmit`	Every task
2	Unit Tests	`npm test`	Low-Medium risk tasks
3	Integration Tests	`npm run test:integration`	Medium-High risk tasks
4	Manual Validation	User flow walkthrough	High-Critical risk tasks

Include the appropriate validation level for each verification step.

根据任务复杂度匹配验证深度：

级别	名称	命令	适用场景
1	语法与风格	`npm run lint` , `tsc --noEmit`	所有任务
2	单元测试	`npm test`	低-中风险任务
3	集成测试	`npm run test:integration`	中-高风险任务
4	手动验证	用户流程走查	高-关键风险任务

每个验证步骤都要应用相应的验证级别。

Verification Checklist

验证检查清单

Output Format

输出格式

markdown

undefined

markdown

undefined

Verification Summary

验证总结

Scope

范围

[What was completed]

[已完成的内容]

Criteria

验证标准

[What was verified]

[验证的内容]

Evidence

证据

Check	Command	Result
Tests	`npm test`	PASS (34/34)
Build	`npm run build`	PASS
Feature	`npm test -- --grep "feature"`	PASS (3/3)

检查项	命令	结果
测试	`npm test`	通过（34/34）
构建	`npm run build`	通过
功能	`npm test -- --grep "feature"`	通过（3/3）

Deviations from Plan (if any)

与计划的偏差（如有）

Planned	Actual	Reason
[Original design]	[What changed]	[Why]

计划内容	实际实现	原因
[原设计]	[变更内容]	[原因]

Status

状态

COMPLETE - All verifications passed with fresh evidence

undefined

已完成 - 所有验证均通过，附全新证据

undefined

Evidence Array Protocol

证据数组规范

Every claim in verification output MUST have a corresponding evidence entry.

Format:

[command] → exit [code]: [result summary]

Rules:

One evidence entry per claim — no claim without evidence, no evidence without claim
Evidence must be from THIS session (not recalled from memory)
Exit codes are mandatory — "looks good" is not evidence
Group evidence by claim type:

EVIDENCE:
  tests: ["CI=true npm test → exit 0: 34/34 passed"]
  build: ["npm run build → exit 0: compiled in 2.3s"]
  feature: ["curl localhost:3000/api/health → exit 0: {status: ok}"]
  regression: ["npm test -- auth.test.ts → exit 0: regression case passes"]

Verification Summary must include this EVIDENCE block before the Status line.

Anti-pattern:

Status: COMPLETE - All verifications passed

without EVIDENCE block = INVALID.

验证输出中的每一项声明都必须有对应的证据条目。

格式：

[命令] → 退出码 [数字]: [结果摘要]

规则：

每项声明对应一条证据——无证据不做声明，无证据不写条目
证据必须来自本次会话（而非记忆）
必须包含退出码——“看起来正常”不算证据
按声明类型分组证据：

EVIDENCE:
  tests: ["CI=true npm test → exit 0: 34/34 passed"]
  build: ["npm run build → exit 0: compiled in 2.3s"]
  feature: ["curl localhost:3000/api/health → exit 0: {status: ok}"]
  regression: ["npm test -- auth.test.ts → exit 0: regression case passes"]

验证总结必须在状态行之前包含此EVIDENCE块。

反模式：

状态：已完成 - 所有验证均通过

但无EVIDENCE块 = 无效。

Goal-Backward Lens (GSD-Inspired)

目标倒推视角（GSD启发）

After standard verification passes, apply this additional check:

在标准验证通过后，应用此额外检查：

Three Questions

三个问题

Truths: What must be OBSERVABLE? (user-facing behaviors)
Artifacts: What must EXIST? (files, endpoints, tests)
Wiring: What must be CONNECTED? (component → API → database)

实际表现： 哪些内容是可观察到的？（用户可见行为）
产物： 必须存在哪些内容？（文件、接口、测试）
关联： 哪些内容必须关联起来？（组件→API→数据库）

Why This Catches Stubs

为什么能检测出存根（Stub）

A component can:

Exist ✓
Pass lint ✓
Have tests ✓
But NOT be wired to the system ✗

Goal-backward asks: "Does the GOAL work?" not "Did the TASK complete?"

一个组件可能：

存在 ✓
通过代码检查 ✓
有测试用例 ✓
但未与系统关联 ✗

目标倒推视角问的是：“目标是否达成？”而非“任务是否完成？”

Quick Check Template

快速检查模板

GOAL: [What user wants to achieve]

TRUTHS (observable):
- [ ] [User-facing behavior 1]
- [ ] [User-facing behavior 2]

ARTIFACTS (exist):
- [ ] [Required file/endpoint 1]
- [ ] [Required file/endpoint 2]

WIRING (connected):
- [ ] [Component] → [calls] → [API]
- [ ] [API] → [queries] → [Database]

Standard verification: exit code 0 ✓
Goal check: All boxes checked?

目标：[用户想要实现的内容]

实际表现（可观察）：
- [ ] [用户可见行为1]
- [ ] [用户可见行为2]

产物（存在）：
- [ ] [所需文件/接口1]
- [ ] [所需文件/接口2]

关联（已连接）：
- [ ] [组件] → [调用] → [API]
- [ ] [API] → [查询] → [数据库]

标准验证：退出码0 ✓
目标检查：所有项都已勾选？

When to Apply

适用场景

After integration-verifier runs
After any "feature complete" claim
Before marking BUILD workflow as done

Iron Law unchanged: Exit code 0 still required. This is an additional verification lens, not a replacement.

集成验证工具运行后
任何“功能完成”声明后
标记构建工作流完成前

铁律不变： 仍需退出码0。这是额外的验证视角，而非替代方案。

Stub Detection Patterns

存根检测模式

After Goal-Backward Lens passes, scan for these stub indicators:

在目标倒推视角检查通过后，扫描以下存根标识：

Universal Stubs

通用存根

bash

undefined

bash

undefined

Check for TODO/placeholder markers

检查TODO/占位符标记

grep -rE "TODO|FIXME|placeholder|not implemented|coming soon" --include=".ts" --include=".tsx" --include="*.js"

Check for empty returns

检查空返回

grep -rE "return null|return undefined|return {}|return []" --include=".ts" --include=".tsx"

undefined

grep -rE "return null|return undefined|return {}|return []" --include=".ts" --include=".tsx"

undefined

React Component Stubs

React组件存根

Pattern	Why It's a Stub
`return <div>Placeholder</div>`	Renders nothing useful
`onClick={() => {}}`	Click does nothing
`onSubmit={(e) => e.preventDefault()}`	Only prevents default, no action
`useState` with no setter calls	State never changes

模式	为什么是存根
`return <div>Placeholder</div>`	未渲染有效内容
`onClick={() => {}}`	点击无任何操作
`onSubmit={(e) => e.preventDefault()}`	仅阻止默认行为，无实际操作
`useState` 无setter调用	状态从未变更

API Route Stubs

API路由存根

Pattern	Why It's a Stub
`return Response.json({ message: "Not implemented" })`	Explicit stub
`return Response.json([])` without DB query	Returns empty, no real data
`return NextResponse.json({})` with no logic	Empty response

模式	为什么是存根
`return Response.json({ message: "Not implemented" })`	明确的存根
`return Response.json([])` 但无数据库查询	返回空内容，无真实数据
`return NextResponse.json({})` 无逻辑处理	返回空响应

Function Stubs

函数存根

Pattern	Why It's a Stub
`throw new Error("Not implemented")`	Will crash at runtime
`console.log("TODO")`	Debug artifact
`// TODO: implement`	Marked incomplete

模式	为什么是存根
`throw new Error("Not implemented")`	运行时会崩溃
`console.log("TODO")`	调试残留
`// TODO: implement`	标记为未完成

Quick Stub Check

快速存根检查

bash

undefined

bash

undefined

Run before claiming completion

在宣称完成前运行

grep -rE "(TODO|FIXME|placeholder|not implemented)" src/ grep -rE "onClick={?() => {}}?" src/ grep -rE "return (null|undefined|{}|[])" src/


**If any stub patterns found:** DO NOT claim completion. Fix or document why it's intentional.

grep -rE "(TODO|FIXME|placeholder|not implemented)" src/ grep -rE "onClick={?() => {}}?" src/ grep -rE "return (null|undefined|{}|[])" src/


**若发现任何存根模式：** 不要宣称完成。修复或说明为何是故意设置的。

Wiring Verification (Component → API → Database)

关联验证（组件→API→数据库）

Artifacts can exist, pass lint, and have tests but NOT be wired to the system.

Component → API Check:

bash

undefined

产物可能存在、通过代码检查、有测试用例，但未与系统关联。

组件→API检查：

bash

undefined

Does component actually call the API?

组件是否实际调用API？

grep -E "fetch(['"].*api|axios.(get|post)" src/components/

Is response actually used?

响应是否实际被使用？


**API → Database Check:**
```bash


**API→数据库检查：**
```bash

Does API actually query database?

API是否实际查询数据库？

grep -E "prisma.|db.|mongoose." src/app/api/

Is result actually returned?

查询结果是否实际返回？

grep -E "return.*json.*data|Response.json" src/app/api/


**Red Flags:**
| Pattern | Problem |
|---------|---------|
| `fetch('/api/x')` with no `await` | Call ignored |
| `await prisma.findMany()` → `return { ok: true }` | Query result discarded |
| Handler only has `e.preventDefault()` | Form does nothing |

**Line Count Minimums:**
| File Type | Minimum Lines | Below = Likely Stub |
|-----------|---------------|---------------------|
| Component | 15 | Too thin |
| API route | 10 | Too thin |
| Hook/util | 10 | Too thin |

grep -E "return.*json.*data|Response.json" src/app/api/


**危险信号：**
| 模式 | 问题 |
|---------|---------|
| `fetch('/api/x')` 无`await` | 调用被忽略 |
| `await prisma.findMany()` → `return { ok: true }` | 查询结果被丢弃 |
| 处理函数仅包含`e.preventDefault()` | 表单无任何操作 |

**行数最小值：**
| 文件类型 | 最小行数 | 低于此值=可能是存根 |
|-----------|---------------|---------------------|
| 组件 | 15 | 内容过简 |
| API路由 | 10 | 内容过简 |
| Hook/工具函数 | 10 | 内容过简 |

Export/Import Verification

导出/导入验证

Exports can exist but never be consumed. Check that key exports are actually used:

bash

undefined

导出的内容可能存在但从未被使用。检查关键导出是否实际被使用：

bash

undefined

Check if export is imported AND used (not just imported)

检查导出是否被导入且使用（不只是导入）

check_export_used() { local export_name="$1" grep -r "import.$export_name" src/ --include=".ts" --include=".tsx" | wc -l grep -r "$export_name" src/ --include=".ts" --include="*.tsx" | grep -v "import|export" | wc -l }

Example: Check auth exports are consumed

示例：检查auth导出是否被使用

check_export_used "getCurrentUser" check_export_used "useAuth"


**Export Status:**
| Status | Meaning | Action |
|--------|---------|--------|
| CONNECTED | Imported AND used | ✓ Good |
| IMPORTED_NOT_USED | Import exists but never called | Remove dead import or implement |
| ORPHANED | Export exists, never imported | Dead code or missing integration |

check_export_used "getCurrentUser" check_export_used "useAuth"


**导出状态：**
| 状态 | 含义 | 操作 |
|--------|---------|--------|
| 已关联 | 已导入且使用 | ✓ 正常 |
| 已导入未使用 | 存在导入但从未调用 | 移除无用导入或实现功能 |
| 孤立 | 存在导出但从未被导入 | 无用代码或缺失集成 |

Auth Protection Verification

权限保护验证

Sensitive routes must check authentication:

bash

undefined

敏感路由必须检查权限：

bash

undefined

Find routes that should be protected

找出需要保护的路由

protected_patterns="dashboard|settings|profile|account|admin" grep -r -l "$protected_patterns" src/app/ --include="*.tsx"

For each, verify auth usage

对每个路由验证权限使用情况

check_auth_protection() { local file="$1" grep -E "useAuth|useSession|getCurrentUser|isAuthenticated" "$file" grep -E "redirect.*login|router.push.*login" "$file" }


**If sensitive route lacks auth check:** Add protection before claiming completion.

check_auth_protection() { local file="$1" grep -E "useAuth|useSession|getCurrentUser|isAuthenticated" "$file" grep -E "redirect.*login|router.push.*login" "$file" }


**若敏感路由缺少权限检查：** 在宣称完成前添加保护。

The Bottom Line

底线

No shortcuts for verification.

Run the command. Read the output. THEN claim the result.

This is non-negotiable.

验证无捷径。

运行命令，查看输出，再做出声明。

这是不可协商的要求。

Completion Guard (Final Gate Before Router Contract)

完成关卡（Router Contract前的最后一关）

IMMEDIATELY before writing
### Router Contract (MACHINE-READABLE)
, verify ALL:

Acceptance criteria met? — Re-read task description. Check each criterion. Any gap = STATUS:FAIL
Evidence array complete? — Every claim has
```
[command] → exit [code]
```
entry from THIS session
No stubs in changed files? — Run stub detection on files YOU modified (not entire repo)
Fresh verification? — Last test/build command ran in THIS message (not earlier in conversation)

If ANY check fails: Fix it FIRST, then re-run Completion Guard. Do NOT emit Router Contract with STATUS:PASS/FIXED/APPROVE until all 4 pass.

This is the LAST gate. No exceptions. No "close enough."

在编写
### Router Contract (MACHINE-READABLE)
前，必须立即验证以下所有内容：

验收标准是否满足？ — 重新阅读任务描述，核对每条标准。任何差距=状态：失败
证据数组是否完整？ — 每项声明都有来自本次会话的
```
[命令] → 退出码 [数字]
```
条目
变更文件中是否无存根？ — 对你修改的文件运行存根检测（而非整个仓库）
是否为全新验证？ — 最后一次测试/构建命令是在本次消息中运行的（而非对话早期）

若任意检查失败： 先修复问题，再重新运行完成关卡。在所有4项都通过前，不要输出Router Contract并标记状态：通过/已修复/批准。

这是最后一关。无例外。无“差不多”。