By name: verification-before-completion description: "Use when about to claim work is complete, fixed, or passing, or before commit, PR, or task completion, and fresh verification evidence must exist first." allowed-tools: Read Grep Glob Bash LSP
Verification Before Completion
DIVERGENCE FROM superpowers:verification-before-completion: Forked. The Iron Law, the Gate Function, and the "evidence before claims" doctrine are core discipline assumed here. Because superpowers is NOT loaded when cc10x runs solo, the scannable Common Failures table, Red-Flags STOP list, and rationalization→reality rebuttal table are now RESTORED inline (no longer purely deferred upstream) so this skill is self-sufficient. CC10x ADDS: the Authoring Rule (keep gates high), the Self-Critique Gate, Validation Levels, Production-Like Live Proof, the Evidence Array Protocol, the Goal-Backward Lens, Phase-Exit Proof vs Extended Audit, Stub Detection, and the Completion Guard that gates the Router Contract.
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.
Authoring Rule: Keep Gates High
Completion/exit gates MUST appear before ~line 1000 of any skill file, OR be re-stated verbatim at the emission point. A gate below the chunked-read window silently no-ops — the agent never reaches it and ships unverified. (See matt-pocock: "I never reached line 1224.")
This is why cc10x's Iron Law and Completion Guard are deliberately kept high in this file: the Iron Law sits at the top, and the Completion Guard's core checks are re-stated at the Router Contract emission point. Do not bury a gate under long reference tables.
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
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
Common Failures, Red Flags, Rationalizations
These are core verification doctrine. They were once deferred to superpowers, but superpowers is not loaded when cc10x runs solo — so the scannable references live inline here. The operational rule: if you catch yourself using "should/probably/seems", expressing satisfaction before running the command, trusting an agent's success report, or relying on a partial check — STOP, run verification, get evidence, THEN speak. Different words do not exempt the rule; spirit over letter.
Common Failures
| Failure | Why it lies | Fix |
|---|---|---|
| previous-run ≠ fresh | Output is from an earlier message; code changed since | Re-run the command in THIS message |
| linter ≠ compiler | Lint passing says nothing about types/build | Run tsc --noEmit / build, not just lint |
| agent-says-success ≠ verified | A spawned agent's "done" is a claim, not evidence | Demand its evidence array; re-run the gate yourself |
Red Flags — STOP
If any of these appear BEFORE you have run the command, STOP and run it:
- "Great!" / "Perfect!" / "Done!" / "All set!"
- "should pass" / "should work"
- "probably" / "seems fine" / "looks good"
- "I've fixed it" with no exit code yet
Rationalization → Reality
| Rationalization | Reality |
|---|---|
| "It's a trivial change, no need to test" | Trivial changes break builds too — run it |
| "Tests passed earlier" | Earlier ≠ now; the diff invalidated that run |
| "The agent reported success" | A report is a claim; evidence is exit code 0 in this session |
| "Lint is green, so it's fine" | Lint ≠ types ≠ runtime; run the full gate |
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
Self-Critique Gate (BEFORE Verification Commands)
MANDATORY: Check these BEFORE running verification commands:
Code Quality
- Follows patterns from reference files?
- Naming matches project conventions?
- Error handling in place?
- No debug artifacts (console.log, TODO)?
- No commented-out code?
- No hardcoded values that should be constants?
Implementation Completeness
- All required files modified?
- No unexpected files changed?
- Requirements fully met?
- No scope creep?
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.
Production-Like Live Proof
If the accepted plan or current task requires real, seeded, production-like verification, read references/live-production-testing.md before claiming completion.
Use the live harness when the task depends on:
- real API calls
- seeded or resettable data
- browser or worker orchestration
- cross-service side effects
- load or stress behavior
Do not treat replay fixtures, unit tests, or manual spot-checks as equivalent proof when the plan requires live-system evidence.
Verification Checklist
Before marking work complete:
- All relevant tests pass (exit 0) - with fresh evidence
- Build succeeds (exit 0) - with fresh evidence
- Feature functionality verified - with command output
- No regressions introduced - with test output
- Evidence captured for each check - in this message
- Deviations from plan documented - if implementation differed from design
- Appropriate validation level applied for task risk
Output Format
## Verification Summary
### Scope
[What was completed]
### Criteria
[What was verified]
### Evidence
| Check | Command | Exit Code | Result |
|-------|---------|-----------|--------|
| Tests | `npm test` | 0 | PASS (34/34) |
| Build | `npm run build` | 0 | PASS |
| Feature | `npm test -- --grep "feature"` | 0 | PASS (3/3) |
### Deviations from Plan (if any)
| Planned | Actual | Reason |
|---------|--------|--------|
| [Original design] | [What changed] | [Why] |
### Status
COMPLETE - All verifications passed with fresh evidence
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.
Goal-Backward Lens (GSD-Inspired)
After standard verification passes, apply this additional check:
Three Questions
- Truths: What must be TRUE? (observable user or business outcomes)
- Artifacts: What must EXIST? (files, endpoints, tests, records)
- Wiring: What must be WIRED? (component → API → database)
Why This Catches Stubs
A component can:
- Exist ✓
- Pass lint ✓
- Have tests ✓
- But NOT be wired to the system ✗
Phase-Exit Proof vs Extended Audit
Use this distinction when verification gets expensive:
- Phase-exit proof is the non-negotiable minimum:
- truths
- artifacts
- wiring
- fresh scenario evidence
- Extended audit is additional confidence work:
- broader scans
- extra pattern sweeps
- deeper blast-radius checks
Never skip phase-exit proof. If extended audit is not run, say so explicitly instead of implying it happened.
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?
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.
Stub Detection Patterns
After Goal-Backward Lens passes, scan for these stub indicators:
Universal Stubs
# Check for TODO/placeholder markers
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"
React Component Stubs
| 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 |
API Route Stubs
| 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 |
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 |
Quick Stub Check
# 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.
Wiring Verification (Component → API → Database)
Artifacts can exist, pass lint, and have tests but NOT be wired to the system.
Component → API Check:
# Does component actually call the API?
grep -E "fetch\(['\"].*api|axios\.(get|post)" src/components/
# Is response actually used?
grep -A 5 "fetch\|axios" src/components/ | grep -E "await|\.then|setData|setState"
API → Database Check:
# Does API actually query database?
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 |
Export/Import Verification
Exports can exist but never be consumed. Check that key exports are actually used:
# 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
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 |
Auth Protection Verification
Sensitive routes must check authentication:
# 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.
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)
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."