flingjie Verification Before Completion
Overview
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.
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
→ If exit ≠ 0: RUN DIAGNOSIS (see Failure Diagnosis section below)
4. VERIFY: Does output confirm the claim?
- If NO: State actual status with evidence
- If YES: State claim WITH evidence
5. ONLY THEN: Make the claim
Skip any step = lying, not verifying
Failure Diagnosis
When a verify command fails (exit ≠ 0), diagnose the root cause BEFORE reporting. Do not just report "command failed" — explain why and provide a concrete fix.
Diagnosis Pipeline
Command fails (exit ≠ 0)
│
├── Step 1: Parse the command — identify tool name, flags, chain operators
├── Step 2: Match against tool-specific diagnosis rules below
├── Step 3: Scan conversation history for same-pattern failures (aggregation)
├── Step 4: Classify severity (false-positive / tool-usage / code-error / unknown)
└── Step 5: Compose report with root cause + concrete fix + confirmation prompt
Step 1: Parse the Command
| Signal | Example | Meaning |
|---|---|---|
| Tool name | grep, npm, npx, tsc, vitest, curl |
Which rules table to consult |
| Flags | -c, -v, -E, -n, --noEmit |
Refine diagnosis |
| Chain operators | &&, ;, ` |
, $()` |
| Regex metacharacters | |, .*, [, { |
Possible regex syntax issue |
If the command uses && chaining: the failure is at the FIRST non-zero exit
code. All subsequent commands in the chain are skipped — their exit codes are
unknown. Always split && chains or use ; when checking multiple conditions
independently.
Step 2: Tool-Specific Rules
grep
| Signal | Diagnosis | Fix |
|---|---|---|
-c flag, exit=1 |
False positive. grep -c returns exit 1 when count=0. If verifying absence, exit 1 = correct result (0 matches). |
Replace grep -c 'p' file && with (grep -c 'p' file || echo 0) && to tolerate zero matches |
| in pattern, no -E |
Tool usage error. Basic regex does not support alternation. | is treated as literal pipe characters, not OR operator. |
Use grep -E 'pattern1|pattern2' or grep -e pattern1 -e pattern2 |
.*, [, { in pattern, no -E |
Tool usage error. These may need escaping in basic regex. | Use grep -E for extended regex |
| exit=2 | File not found, permission denied, or grep syntax error. | Check the file path exists; check for unescaped special characters in the pattern |
&& chain with multiple grep -c |
False positive risk. An intermediate grep -c returning 0 with exit 1 breaks the chain — you cannot tell which grep succeeded. |
Split into separate commands or use ; instead of &&, evaluating each result individually |
npm / npx
| Signal | Diagnosis | Fix |
|---|---|---|
| exit≠0, stderr present | Extract last 3 lines of stderr — these are usually the actionable error. | Present the stderr snippet as diagnosis |
npm install fails |
Dependency resolution, network, or package not found. | Show stderr; common fixes: --ignore-scripts, --legacy-peer-deps |
npx command not found |
Package not installed or wrong name. | Show stderr; suggest npm ls <pkg> or which <cmd> |
tsc
| Signal | Diagnosis | Fix |
|---|---|---|
exit=2, output contains error TS |
TypeScript compilation errors. | Extract error lines with file:line:col: message. List specific errors. |
--noEmit present |
Type-check only — verify this was the intent. | List the specific type errors found; suggest fixes if patterns are recognizable |
vitest / test runner
| Signal | Diagnosis | Fix |
|---|---|---|
| exit=1, "N failed" in output | Test failures, not a command error. | Extract the failure count and list the first 3 failing test names |
| exit≠0, no test output | Runner did not execute (config error, missing file). | Check the test path; suggest --reporter=verbose for more detail |
curl
| Signal | Diagnosis | Fix |
|---|---|---|
| exit=7 | Failed to connect (network, wrong host, port closed). | Check URL, check if service is running |
| exit=6 | DNS resolution failed. | Check hostname |
| exit=28 | Timeout. | Increase --connect-timeout or --max-time |
Unknown / unlisted tool
Present exit code and any stderr output. Say: "No diagnosis rules for <name>. Raw output: <stderr>."
Step 3: Cross-Attempt Aggregation
Before reporting, scan the current conversation for previous verification failures. Count occurrences of the same tool+pattern combination:
| Count | Action |
|---|---|
| 1 | Normal diagnosis — present root cause + fix |
| 2 | Note "2nd occurrence of same pattern" in report |
| 3-4 | Escalate. "Nth consecutive <tool> failure with same pattern — this is a systematic tool usage issue, not a code problem. Fix the approach, don't retry with the same command." |
| ≥5 | Block. "5th consecutive failure. Stop. The current approach to verification is broken. Before retrying: fix the usage pattern. No further attempts will succeed with the same approach." |
If failures span different tools or patterns, still note the accumulation: "N verification failures this session — consider whether the verification commands themselves need review."
Step 4: Classify Severity
| Classification | Criteria |
|---|---|
| False positive | Desired state (e.g., grep -c returning 0). Exit code ≠0 is correct but command structure is wrong. |
| Tool usage error | Command has a syntax/flag issue. Fixing the command will fix the verification. |
| Code/state error | Command is correct but code/test/config is broken. |
| Unknown | Cannot classify — fall through. |
Step 5: Report Format
Every report must include: root cause, concrete fix, and a confirmation prompt.
For tool usage errors:
## Verification Failed
**Severity:** Tool usage error
**Root cause:** grep basic regex — `\|` alternation requires `-E` flag
**Pattern:** 3rd consecutive grep failure with `\|`
**Fix:** Replace `grep 'A\|B'` with `grep -E 'A|B'`
Apply this fix? (y/n)
For false positives:
## Verification — False Positive
**Root cause:** `grep -c` returned exit 1 on zero matches — this is the desired result (verifying absence works correctly)
**Fix:** Replace `grep -c 'old' file && grep -c 'new' file` with separate commands using `|| echo 0` to tolerate zero-match exit codes
Apply this fix? (y/n)
At block threshold (≥5 same pattern):
## Verification Failed — Blocked (5th consecutive grep failure)
**Pattern:** All 5 failures are grep regex syntax issues
**Action:** Stop. Fix the grep approach before retrying.
**Options:**
1. Use `grep -E` for all alternation patterns
2. Use `grep -e p1 -e p2` instead of `\|`
3. Split `&&` chains into separate verification commands
Which approach?
When to Skip Diagnosis
Fall back to current generic report when:
- The tool is not in the rules table AND stderr is empty or unhelpful
- The failure is clearly a transient one-off (network timeout, rate limit)
Even for unknown tools, always extract and present any stderr output — never show "(no output)" when data is available.
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 |
Red Flags - STOP
- 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
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 |
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
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