verification

name	verification
description	Structured self-check against acceptance criteria BEFORE claiming DONE. Triggers: "I'm done", "verify this", "finished". NOT for sprint retrospection — use self-improvement for that.
allowed-tools	["Bash","Read","Write","Edit","Grep","Glob"]
when_to_use	Use immediately before reporting DONE on any substantive task. Writes an evaluation artifact that finishing-branch / release consume.
produces	docs/superomni/evaluations/evaluation-[branch]-[session]-[date].md
consumes	["docs/superomni/executions/execution-[branch]-[session]-[date].md"]

Preamble (Core)

Status protocol — end every session with one of: DONE (evidence provided) · DONE_WITH_CONCERNS (list each) · BLOCKED (state what blocks you) · NEEDS_CONTEXT (state what you need).

Auto-advance — pipeline: THINK → PLAN → REVIEW → BUILD → VERIFY → RELEASE. Only human gate is spec approval at THINK. On DONE at other stages, print [STAGE] DONE -> advancing to [NEXT-STAGE] and invoke the next skill. On any non-DONE status at any stage, STOP.

Output directory — all artifacts go in docs/superomni/<kind>/<kind>-[branch]-[session]-[date].md. See CLAUDE.md for the full directory map.

TACIT-DENSE — before high-tacit decisions, classify D1 (domain expertise) · D2 (user-facing UX) · D3 (team culture) · D4 (novel pattern). On hit, output TACIT-DENSE [D#]: [question] — My default: [recommendation]. See reference for actions.

Anti-sycophancy — take a position on every significant question. Name flaws directly. No filler ("that's interesting", "you might consider", "that could work").

Telemetry (local only) — at session end, log bin/analytics-log. Nothing leaves the machine.

See preamble-ref.md for detailed protocols.

Verification Before Completion

Goal: Systematically verify that work is complete and correct before declaring done.

Iron Law: Evidence Required

"I think it works" is not evidence. "I believe it's correct" is not evidence. Evidence is: running the code and showing output, passing test results, or observable behavior.

Good Example (Evidence Required)

Agent claims feature is complete.
Evidence provided:
  1. npm test output: "15 tests, 15 passing, 0 failing"
  2. Manual verification: curl -X POST /api/users -> 201 Created
  3. Edge case tested: curl -X POST /api/users (empty body) -> 400 Bad Request
  4. Screenshot: UI renders correctly with new component
Result: DONE — all evidence is observable and reproducible

Bad Example (AVOID)

Agent claims feature is complete.
Evidence provided:
  "I believe the implementation is correct based on the logic"
  "It should work because I followed the pattern from the other module"
Result: NOT ACCEPTABLE — "believe" and "should" are not evidence
[VIOLATED: No test output, no command results, no observable behavior shown]

Common Excuse Rebuttals

Excuse	Rebuttal
"The logic is straightforward, it must work"	Straightforward logic still needs proof — run the test
"I followed the same pattern as module X"	Pattern match is not verification — show the output
"Tests aren't set up for this area"	Then set them up — untestable claims cannot be verified

Current State (auto-injected at skill-load)

The !`` syntax is Anthropic's dynamic context injection — runtime resolves each command before the skill body reaches the LLM.

• Branch / status: !git branch --show-current && git status -s
• Diff stat (since main): !git diff --stat main...HEAD 2>/dev/null | tail -10
• Latest plan path: !ls -t docs/superomni/plans/plan-*.md 2>/dev/null | head -1
• Plan unchecked count: !p=$(ls -t docs/superomni/plans/plan-*.md 2>/dev/null | head -1); [ -n "$p" ] && grep -c '^- \[ \]' "$p" || echo 0
• Latest evaluation path: !ls -t docs/superomni/evaluations/evaluation-*.md 2>/dev/null | head -1

The Verification Checklist

Run through this before reporting any status:

0. Goal Alignment Check (run first)

Before any technical checks, verify the output achieves what the user originally asked for.

# Read acceptance criteria from spec or plan
_SPEC=$(ls docs/superomni/specs/spec-*.md 2>/dev/null | sort | tail -1)
_PLAN=$(ls docs/superomni/plans/plan-*.md 2>/dev/null | sort | tail -1)
cat "$_SPEC" 2>/dev/null | grep -A 30 "Acceptance Criteria" | head -40 || \
  cat "$_PLAN" 2>/dev/null | grep -A 20 "Success Criteria" | head -30 || \
  echo "No docs/superomni/specs/spec-*.md or docs/superomni/plans/plan-*.md found"

For each acceptance criterion in docs/superomni/specs/spec-.md or docs/superomni/plans/plan-.md:

Criterion	Met?	Evidence
[criterion from spec]	✓/✗	[specific proof: test output, observable behavior, or code reference]

If no docs/superomni/specs/spec-*.md exists:

• State what user goal this change fulfills
• List observable outcomes that prove the goal is met

Gate: Cannot report DONE if any P0 acceptance criterion is unmet.

1. Functional Verification

• Does it do what the spec/plan/ticket says it should do?
• Run the actual code and observe the actual output
• Test the happy path: does it work for the normal case?
• Test edge cases: empty input, max values, null/nil?
• Test error conditions: does it fail gracefully?

# Run tests
npm test 2>&1 | tail -20
# or
pytest -v 2>&1 | tail -20
# or
go test ./... 2>&1 | tail -20

2. Test Verification

• Are there tests? (If new code was written, tests are mandatory — this is a hard gate)
• Do all tests pass?
• Do tests verify behavior (not just implementation)?
• Are tests independent (can run in any order)?
• Was TDD followed? (test written before implementation)

Hard gate for new code: If new source code was written and no tests exist for it, report BLOCKED — do not advance to DONE until tests are added. The only valid exception is a documented reason (pure UI layout, throw-away prototype).

# Step 1: List source files changed (exclude tests and docs)
git diff HEAD --name-only | grep -vE "(test|spec|\.md$|\.txt$)" | head -10

# Step 2: List test files changed
git diff HEAD --name-only | grep -E "(test|spec|_test\.|\.test\.)" | head -10

# Step 3: Check if any source file has a corresponding test file
# For each changed source file, search for a test file by base name
for f in $(git diff HEAD --name-only | grep -vE "(test|spec|\.md$)"); do
  base=$(basename "$f" | sed 's/\..*//')
  found=$(find . -name "*${base}*test*" -o -name "*${base}*spec*" -o \
          -name "test_*${base}*" 2>/dev/null | head -1)
  if [ -z "$found" ]; then
    echo "MISSING TESTS: $f (no test file found for '$base')"
  else
    echo "HAS TESTS: $f → $found"
  fi
done

3. Regression Verification

• Do existing tests still pass?
• Did you break anything adjacent?

# Run full test suite (not just new tests)
npm test 2>&1 | grep -E "(PASS|FAIL|Error)" | head -20

4. Completeness Verification

• Are all acceptance criteria from the spec/plan met?
• Are error paths handled?
• Is there appropriate logging for debuggability?
• Are edge cases covered?
• Is the code readable without requiring comments to explain "what"?

5. No Regressions Checklist

• Reviewed the diff: git diff HEAD
• No unintended files changed
• No debug code left in (console.log, print, debugger)
• No TODO left unresolved that blocks the task

# Quick diff review
git diff HEAD --stat
git diff HEAD | grep "console.log\|debugger\|TODO\|FIXME\|print(" | head -10

6. Blast Radius Check

• How many files were changed? (git diff HEAD --stat | tail -1)
• If >5 files: was this flagged to the user?
• Any unexpected files in the diff?

Independent Gate: planner-reviewer Agent (Evaluation Mode)

For a context-isolated independent verdict (recommended on ≥5-step waves, any DONE_WITH_CONCERNS step, or the final wave), dispatch the planner-reviewer agent in evaluation mode with:

• The spec/plan acceptance criteria (from docs/superomni/specs/spec-*.md or docs/superomni/plans/plan-*.md)
• All checklist results from above
• Test output
• Files changed

The agent provides an independent EVALUATION REPORT with verdict APPROVED / APPROVED_WITH_NOTES / CHANGES_REQUIRED / EVALUATION_INCOMPLETE. Incorporate its TOP FINDING into the Verification Report below. (Evaluation content was consolidated from the retired evaluator agent into planner-reviewer evaluation mode.)

If the agent returns CHANGES_REQUIRED: set status to BLOCKED and do NOT advance to RELEASE until the flagged issues are resolved.

Verification Report

After completing the checklist and receiving the independent verdict:

VERIFICATION REPORT
════════════════════════════════════════
Task:              [what was being implemented/fixed]
Tests run:         [N tests, N passing, N failing]

Goal Alignment:
  Spec/plan used:  [docs/superomni/specs/spec-*.md | docs/superomni/plans/plan-*.md | user request]
  ✓/✗ [acceptance criterion 1] — [evidence]
  ✓/✗ [acceptance criterion 2] — [evidence]
  User goal achieved: YES | PARTIAL | NO

Acceptance criteria:
  ✓ [criterion 1]
  ✓ [criterion 2]
  ✗ [criterion 3] — FAILED (explain why)
Files changed:     [N files]
Regressions:       [none | list any]
Evidence:          [test output snippet or observed behavior]

Status: DONE | DONE_WITH_CONCERNS | BLOCKED
Concerns (if any):
  - [concern 1 with recommendation]
════════════════════════════════════════

Save Evaluation Report

After completing verification, save the report as a persistent Markdown document:

EVAL_DIR="docs/superomni/evaluations"
mkdir -p "$EVAL_DIR"
BRANCH=$(git branch --show-current 2>/dev/null | tr '/' '-' || echo "main")
TIMESTAMP=$(date +%Y-%m-%d-%H%M%S)
EVAL_FILE="$EVAL_DIR/evaluation-${BRANCH}-${TIMESTAMP}.md"

Write the full VERIFICATION REPORT block (including all checklist results, test output, and goal alignment table) to $EVAL_FILE in this format:

# Verification Evaluation: [branch]

**Date:** [date]
**Branch:** [branch]
**Task:** [what was being verified]

## Checklist Results

| Check | Result | Notes |
|-------|--------|-------|
| Functional verification | ✓/✗ | |
| Test verification | ✓/✗ | |
| Regression verification | ✓/✗ | |
| Completeness | ✓/✗ | |
| No regressions | ✓/✗ | |
| Blast radius | ✓/✗ | |

## Goal Alignment

Spec/plan used: [docs/superomni/specs/spec-*.md | docs/superomni/plans/plan-*.md | user request]

| Criterion | Met? | Evidence |
|-----------|------|----------|
| [criterion 1] | ✓/✗ | [proof] |

## Evidence

[Test output snippet or observed behavior]

## Verdict

[Paste full VERIFICATION REPORT block here]

**Status:** DONE | DONE_WITH_CONCERNS | BLOCKED

echo "Evaluation saved to $EVAL_FILE"

This file is the permanent task evaluation record. It feeds into self-improvement and future sprint retrospectives.

When Verification Fails

If any check fails:

1. P0 failure (tests fail, criteria not met): report BLOCKED or go fix it
2. P1 failure (edge case missing, partial coverage): report DONE_WITH_CONCERNS with specific notes
3. Ambiguous (can't tell if it's working): report NEEDS_CONTEXT with specific question