verification-gate

Files (1)

• SKILL.md

SKILL.md (first lines)

# Verification Gate — Mandatory Skill

**Agent:** Builder (before result.md), Janitor (during validation)
**Phase:** BUILD Phase 3 completion, BUILD Phase 4, DEBUG Phase 4, REVIEW Phase 3
**Priority:** CRITICAL — This skill is NON-NEGOTIABLE before ANY completion claim

---

## IRON LAW

**NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE.**

"I ran the tests earlier" is not evidence. "The tests should pass" is not evidence.
Evidence is: you ran the command NOW, you read the output NOW, the output proves the claim.

---

## The Gate Function

Every completion claim — whether in `result.md`, verbal statements, or status updates — MUST pass through this 5-step gate:

### Step 1: IDENTIFY
**What specific claims am I making?**

Write them down explicitly:
```
Claims:
1. All tests pass
2. Typecheck passes
3. Feature X works as specified
4. No regressions introduced
```

### Step 2: RUN
**Execute the verification commands RIGHT NOW.**

Not "I ran them earlier." Not "they passed last time." Run them NOW.

```bash
# Example verification commands:
npx tsc --noEmit              # Typecheck
bun test                       # Unit tests
bun test -- --run             # All tests (no watch mode)
```

### Step 3: READ
**Read the ACTUAL output.**

Not "the exit code was 0." Not "it looked green." Read the output.

```
# GOOD: Actually reading output
"Tests: 47 passed, 0 failed. Time: 2.3s"

# BAD: Assuming from exit code
"Tests passed" (without reading how many, which ones)
```

### Step 4: VERIFY
**Does the output PROVE each claim?**

For each claim from Step 1, match it to specific evidence from Step 3:

```
Claim 1: "All tests pass"
Evidence: "Tests: 47 passed, 0 failed" — VERIFIED ✓

Claim 2: "Typecheck passes"
Evidence: "tsc --noEmit completed with 0 errors" — VERIFIED ✓

Claim 3: "Feature X works as specified"
Evidence: Test "should handle discount for gold tier" passes — VERIFIED ✓
Evidence: Test "should reject negative prices" passes — VERIFIED ✓
```

### Step 5: CLAIM
**Only NOW state the result.**

Write the claim with evidence attached. No claim without evidence.

```markdown
## result.md
- typecheck_status: PASS (tsc --noEmit: 0 errors)
- test_status: PASS (47/47 tests passing)
- feature_verified: YES (see tests: discount-gold, reject-negative)
```

---

## Forbidden Language

These phrases indicate UNVERIFIED claims. If you catch yourself using them, STOP and re-verify:

| Forbidden Phrase | What It Really Means | Replace With |
|---|---|---|
| "should work" | "I haven't tested it" | Run the test. Report the result. |
| "probably fine" | "I'm guessing" | Verify. Report evidence. |
| "seems to work" | "I glanced at it" | Run the full verification. Report output. |
| "I believe it passes" | "I'm remembering, not verifying" | Run it again. Report fresh output. |
| "Done!" | "I stopped working" | Run Gate Function. Then report. |
| "Everything looks good" | "I haven't checked everything" | List what you checked. Report evidence for each. |
| "No issues found" | "I didn't look very hard" | List what you checked. Report evidence. |
| "Tests are green" | Potentially stale | Run them NOW. Report the output. |
| "Should be backwards compatible" | "I haven't verified the API surface" | Check callers. Run integration tests. |
| "I fixed it" | "I changed something" | Prove it: failing test → fix → passing test. |

### Language Policing Rule
If a `result.md` or completion statement contains ANY forbidden phrase, the Janitor MUST:
1. Flag it immediately.
2. Request re-verification with fresh evidence.
3. Not proceed to APPROVE until forbidden language is replaced with evidence.

---

## Rationalization Table

| What You'll Think | Why It's Wrong |
|---|---|
| "I already tested this 5 minutes ago." | Code changes in 5 minutes. An edit you made since could have broken it. Run it again. |

From lshtram/nso, MIT.

More from lshtram/nso