affectionatec/agentic-engineering / skills/independent-verification
independent-verification
VerifiedUse when a task or milestone claims completion and must be verified before being marked done, when acting as a verifier sub-agent checking a producer's work, or when a "done" claim needs evidence. Triggers on "verify this task", "is this actually done", "acceptance check", "run verification", any completion claim, any π β β status transition, or dispatching a maker-checker review loop.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.7 KB |
SKILL.md
View on GitHub---
name: independent-verification
description: Use when a task or milestone claims completion and must be verified before being marked done, when acting as a verifier sub-agent checking a producer's work, or when a "done" claim needs evidence. Triggers on "verify this task", "is this actually done", "acceptance check", "run verification", any completion claim, any π β β
status transition, or dispatching a maker-checker review loop.
---
# Independent Verification β The Maker-Checker Gate
> **Core constraint:** The agent that wrote the code never grades it. "Done" is a verdict returned by a verifier with fresh context β not a claim made by the producer.
## Quick Reference
| | |
|---|---|
| **Use when** | A task or milestone claims completion; before any task is marked β
in STATUS |
| **Skip when** | Throwaway prototyping the user has explicitly exempted, or pure doc typo fixes |
| **Output** | Verdict entry appended to `docs/verification-log.md` (PASS / FAIL per criterion, with evidence) |
| **Sequence** | IMPL PLAN task built β **VERIFY** β STATUS records β
(loops every task) |
| **Iron rule** | Fresh context. The verifier never sees the producer's conversation, and never edits code. |
| **Sibling skills** | [[project-kickoff-prd]] Β· [[technical-specification]] Β· [[architecture-decision-record]] Β· [[implementation-plan]] Β· [[status-tracker]] Β· [[git-workflow]] |
## Why This Exists
The deadliest failure mode of an autonomous coding session is not a crash β it is **claiming completion without completing**. Models grade their own homework too generously: the same model that wrote the code will rate it "looks good" every time, and an agent without an external gate declares "done" at 30% completion with full confidence.
The fix is structural, not behavioral. You cannot prompt a producer into objectivity β you separate the roles:
1. The **done condition** is written down before work starts (IMPL PLAN task + SPEC acceptance criteria). The producer cannot redefine "done" mid-run.
2. The **producer** builds and self-checks. Self-check is necessary, never sufficient.
3. The **verifier** β fresh context, different conversation, optionally a different model β executes the done condition as written and returns a verdict with evidence.
4. Only a **PASS verdict** moves the task to β
in STATUS.
## Roles
| Role | Does | Must NOT |
|------|------|----------|
| **Producer** | Implements the task, runs self-checks (lint, tests), assembles the evidence package | Mark its own task done Β· edit acceptance criteria Β· write the verdict |
| **Verifier** | Reads the done condition first, re-runs every verification command, inspects the diff, writes the verdict | Fix code Β· inherit the producer's conversation Β· negotiate or reinterpret criteria |
**Fresh context is the whole point.** Run the verifier as a sub-agent with no shared conversation, a fresh session, or a separate agent entirely. A verifier that saw the producer's reasoning inherits the producer's blind spots β that is verification theater, not verification.
> **If this suite is installed as the Claude Code plugin**, a ready-made verifier ships with it: dispatch the bundled `verifier` sub-agent (explicitly via `@agent-agentic-engineering:verifier`, or let delegation pick it up). Sub-agents start with fresh context by construction β the isolation this skill requires is structural, not a discipline to remember.
## Verifier Protocol
### Step 1: Read the contract β before reading the code
In this order:
1. The task's done condition (IMPL PLAN task entry β acceptance criteria + declared file list)
2. The SPEC acceptance criteria the task references (each carries its verification command)
3. `AGENTS.md` β canonical test/lint/build commands and boundaries
Reading the criteria before the diff prevents the verifier from rationalizing what it sees.
### Step 2: Inspect the diff
- Identify every file created or modified
- **Scope check:** does the diff stay within the task's declared file list? Flag any drift.
- **Test ratchet check:** were any tests deleted, skipped, or weakened? Test count must not decrease. Deleting tests to make a run pass is an automatic FAIL.
### Step 3: Execute the done condition
- Run every verification command exactly as written in the SPEC / IMPL PLAN. No interpretation, no substitution.
- Record exit codes and the key output lines β evidence, not impressions.
- Run the full test suite, not just the new tests. Report exact counts and compare against the baseline from the previous verdict.
### Step 4: Render the verdict
- Verdict is **binary per criterion**: PASS or FAIL. "Mostly works" is FAIL.
- Overall verdict is PASS only if every criterion passes, the ratchet holds, and no unexplained scope drift exists.
- For failures: state what was expected vs. what was observed. Locate the gap; do not write the fix.
## Verdict Template
> Append to `docs/verification-log.md`, newest first. Entries are append-only β never edit a past verdict.
````markdown
## YYYY-MM-DD β [Task ID]: [Task Title] β VERDICT: PASS | FAIL
> Verifier context: fresh session/sub-agent Β· Diff: [commit range or branch]
**Test ratchet:** baseline [N] β now [M] (β
holds / β decreased)
**Scope:** clean / β οΈ drift β [files touched outside the task's declared list]
**Commands executed:**
| Command | Exit | Key output |
|---------|------|-----------|
| `pytest tests/ -v` | 0 | 147 passed (baseline 142, +5 new) |
| `ruff check` | 0 | clean |
**Criteria:**
| # | Criterion | Verdict | Evidence |
|---|-----------|---------|----------|
| 1 | Given [precondition] When [action] Then [outcome] | β
PASS | `pytest tests/test_auth.py::test_expiry` 1/1 |
| 2 | Given [edge case] When [action] Then [handling] | β FAIL | expected 409 CONFLICT, observed 500 |
**Failure detail (if any):** [expected vs. observed, file/line of the gap β no fix proposals]
**Round:** [1/3] [if FAIL: producer fixes and resubmits]
````
## Loop Rules (Producer β Verifier)
1. **FAIL β producer fixes β re-verify.** Each round gets a new verdict entry. The fix round only addresses the failed criteria; the verifier still re-runs the full suite (regressions hide in fixes).
2. **Circuit breaker: three rounds maximum.** After the third consecutive FAIL on the same task, stop. Escalate to the user with the verdict history. A loop that cannot converge is burning tokens on a problem that needs a human decision β usually the task or spec is wrong, not the code.
3. **Criteria are locked while the loop runs.** Weakening a criterion to make it pass requires explicit user approval β and an ADR if the change is architectural. The producer asking the verifier to "skip that one" is the exact failure this skill exists to prevent.
4. **The test ratchet is non-negotiable.** Suite count only goes up. A deleted or skipped test is an automatic FAIL regardless of other criteria.
5. **Only PASS moves STATUS to β
.** The STATUS module table references the verdict (date + task ID). A β
without a verdict entry is a claim, not a completion.
## The Human Gate (After the Machine Verdict)
A machine PASS is necessary β not sufficient β for merge:
- **A human reads the diff before merge** and must be able to explain the change in their own words. If you can't explain it, you don't own it β you've accumulated comprehension debt that compounds with every merge.
- The verdict entry doubles as the human's review digest: what changed, what was verified, what the risks were.
- The faster the loop produces code, the more this gate matters. An unattended loop is also a loop making unattended mistakes β verification gives the "done" claim weight, but reading what your agent wrote is what keeps you the engineer.
## Cost Discipline
Independent verification doubles model invocations per task. Spend it where it pays:
- **Always verify:** plan tasks, anything merging to main, anything touching data, auth, money, or public APIs.
- **User may exempt:** throwaway spikes, prototypes explicitly marked disposable.
- A cheaper/faster model is acceptable as verifier for mechanical checks (commands, counts, diffs); use a strong model when criteria require judgment.
## Anti-Patterns (Do Not)
| Anti-Pattern | Why It Fails |
|--------------|--------------|
| Verifier shares the producer's session | Inherits the same blind spots β verification theater |
| Verifier fixes the code it's checking | It just became a producer; the verdict is now self-graded |
| "Looks good" without commands run | A verdict without evidence is a claim with extra steps |
| Re-litigating the spec during verification | The gate checks compliance, not design. Design concerns β flag for ADR, verdict stays on the written criteria |
| Letting the producer pre-summarize "what to check" | The done condition on disk is the input β not the producer's framing of it |
| Infinite fix-verify ping-pong | No convergence = wrong task or wrong spec. Circuit breaker at 3 rounds, escalate |
| Marking β
on a producer claim | The exact failure mode this skill exists to prevent |
## Relationship to Other Documents
- **IMPL PLAN** defines each task's done condition β the verifier executes it as written ([[implementation-plan]])
- **SPEC** holds acceptance criteria with verification commands per criterion ([[technical-specification]])
- **STATUS** records β
only with a verdict reference; the π state marks "built, awaiting verification" ([[status-tracker]])
- **GIT WORKFLOW** puts the work on a branch and a draft PR before verification; a PASS verdict is what flips the PR from draft to ready ([[git-workflow]])
- **AGENTS.md** defines the canonical commands the verifier runs ([[agents-md-template]])
- **ADR** captures any criteria change that survives escalation ([[architecture-decision-record]])
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why β repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" β or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself β your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |