verification-before-completion

name	verification-before-completion
description	Use when an imminent complete, fixed, passing, ready, or safe claim—or final status after edits/tests—needs an evidence gate; not as an implementation substitute.
argument-hint	<claim, task, plan, or changed-file scope>

Verification Before Completion for Claude Code

This generated file is the Claude Code-facing runtime skill document. Claude Code slash commands should read this file directly; maintainers edit the source documents listed below instead.

Generated Runtime Composition

Source order:

• ../../docs/skill-core/verification-before-completion.md
• ../../docs/platforms/claude-code-verification-before-completion.md

The sections below are already composed for this platform. Do not ask the runtime model to load another platform's runtime document or invocation syntax.

Source: docs/skill-core/verification-before-completion.md

Verification Before Completion

Do not claim success without fresh evidence. This skill is both a standalone lightweight final gate and the final evidence gate inside ralph and ultrawork — when those stronger workflows are active, verify the final claim without weakening their PRD, review, cleanup, or QA requirements. Do not use it as a substitute for ralph when the work needs PRD tracking, cleanup, and review loops.

Invariants

V1. No completion claim without fresh, acceptance-mapped evidence verified
    in the current work pass; a previous run is not fresh evidence unless
    nothing it depends on changed.
V2. A success status is not acceptance: HTTP 2xx with an empty or error
    body, exit 0 with no state change, or a "done" log line without the
    observable effect is missing evidence, not a pass.
V3. A command list is not proof: every acceptance criterion maps to
    evidence with coverage strength, freshness, and audit status.
V4. For STANDARD/THOROUGH behavior-changing claims whose proving tests or
    implementation were authored or accepted by the current agent, an
    independent `verifier` audit is required — this self-gate never
    substitutes for it.
V5. A merge or integration step is evidence-changing unless the caller
    proves the final files and dependencies are identical to the
    verifier-audited state.
V6. Reuse the caller's canonical ledger in place, recording only the delta;
    never rewrite an unchanged parallel acceptance mapping.
V7. Secrets and PII are redacted to labeled placeholders before any
    real-surface artifact, command output, or log is recorded as evidence.
V8. Final evidence gate: return the result to the caller; never chain to
    another workflow skill.

Required Gate

No completion claim may be made without fresh, acceptance-mapped evidence verified in the current work pass [V1].

Before making a completion claim, complete every step below; the claim is invalid if any step is skipped or rests on stale evidence:

1. State the exact claim to verify.
2. Identify the command, artifact, diff inspection, or checklist that can prove it.
3. Run or inspect the evidence fresh in the current work pass.
4. Compare evidence to the canonical AC-ID ledger, mark changed or stale rows, and record the delta since the last independent audit [V6].
5. Complete the Risk Check Before Completion below.
6. Report skipped checks and residual risk.
7. For a STANDARD or THOROUGH behavior-changing claim whose proving tests or implementation were authored or accepted by the current agent, confirm a separate-context independent verifier audit ran per the carve-out [V4]. If no separate context is available, record dispatch-unavailable as a blocker and return blocked/PAUSED to the caller; inline command reruns cannot satisfy the audit.
8. When a code-reviewer was dispatched, record perspective-pair plus the active platform's pair-mode value: it is always a perspective-diverse pair when dispatched, and the named THOROUGH trigger selects only escalated platform diversity. An inline fallback requires a reason. Missing review topology is a named ledger gap, not a pass.

If no meaningful command exists, inspect the changed files and write a manual verification checklist instead of implying automated confidence.

Acceptance-To-Evidence Mapping

Reuse the caller's canonical ledger when present [V6]; a standalone invocation creates this compact mapping once [V3]:

Acceptance-to-evidence mapping:
- AC ID / criterion:
  - Evidence:
  - Coverage strength: direct | indirect | manual | missing
  - Freshness source:
  - Audit status: actual | audited | stale | blocked
  - Gap or residual risk:

Direct evidence is a focused test, scenario, or inspection that would fail if the requested behavior were absent or wrong. Indirect evidence — broad suites, lint, typecheck, formatting, compile — supports but never replaces direct acceptance evidence for behavior-changing work. In STANDARD or THOROUGH mode, for user-facing or behavior-changing work, direct evidence must be an artifact observed from the real surface (actual command output, terminal or UI capture, an HTTP response body); "should work", "looks correct", and a printed or --dry-run command are indirect at best. This bar does not apply to LIGHT or trivial work. New tests are supporting evidence, not sufficient completion proof, when a viable nearby baseline or smoke check could catch regressions.

Evidence Rules

• For behavior-changing work, verify RED/GREEN/REFACTOR evidence or a documented TDD exception.
• Redact secrets and PII before recording any evidence, keeping only the non-sensitive shape (status line, lengths, hashes, short non-secret prefixes) [V7].

Risk Check Before Completion

Before the final claim, actively look for the most likely way local green evidence could still miss the real user, maintainer, or uncovered behavior. Keep the questions category-level and requirements-driven, not case-specific.

Risk check before completion:
- Acceptance criteria covered by direct evidence:
- Acceptance criteria only covered indirectly:
- Contract surface and semantic model checked:
- Baseline guard: existing test, smoke, inspection, or no viable baseline reason:
- Likely category risk a skeptical maintainer would test (for example
  contract-surface mismatch, semantic-lifecycle/state miss, hidden regression):
- One more useful failing test I would write if time allowed:
- Completion claim:

The "one more useful failing test" field is non-blocking residual-risk documentation. Do not implement it or use it to block completion unless it maps to an unmet AC ID or an approved named risk; otherwise record it as not relevant with the reason.

The completion claim classifies the result as: complete with direct evidence, baseline guard satisfied or unavailable with reason, and no blocking review findings; locally verified with explicit residual risk; or blocked / failed verification because evidence or review blockers remain. Report every material finding regardless of class: the blocking predicate determines the completion result, not disclosure; non-blocking findings remain visible as residual risk.

Validation Check

When measurable evidence influenced the work, record a validation check: the evidence used, supported acceptance criterion or user outcome, proof and gap, recurring risk addressed, similar-work expectation, excluded case-specific details, added process cost, and completion claim. Treat metric movement as a diagnostic signal, never the acceptance criteria: reject completion claims whose only support is metric movement, unseen-check guessing, fixture knowledge, task-name-specific guidance, or a metric that does not match the real user, maintainer, operator, or public contract. Also reject process inflation that would not help a skeptical maintainer on similar work.

Agent Roles

Dispatch verifier by default for nontrivial completion claims on subagent-capable hosts — independent evidence mapping can change the ship/block decision or expose residual risk, and independence requires a separate context [V4]. Add a code-reviewer (security lens included) when the changed scope, verification tier, or user-facing risk warrants it. Apply the active platform's dispatch authorization; do not ask for per-run subagent approval when standing authorization covers these roles. Every direct role dispatch reuses the target role's required identity/result envelope and adds only this workflow's claim and evidence delta. A standalone invocation creates compact Packet, run/session, and task IDs plus the target revision/diff fingerprint from its current claim and scope; adapters pass that packet unchanged. Inline verification is appropriate only for tiny direct checks where V4 does not require an independent audit. When V4 requires one and dispatch is unavailable, record the blocker and return blocked/PAUSED; inline evidence may supplement the record but cannot satisfy the audit.

Agent	Use
verifier	map the claim to evidence and run or inspect the required checks; scenario lens for user-facing flows; an unconditionally single self-host independent pass, never part of a reviewer pair
code-reviewer	review behavior-affecting code or workflow prompt changes when risk warrants it; security lens for auth, data, file system, network, secrets, or policy-sensitive changes; always a perspective-diverse pair when dispatched, while the named THOROUGH trigger selects only escalated platform diversity (pair synthesis: merged findings)

A dispatched code-reviewer uses two same-role instances, each running the full role: Lens A = adversarial correctness + security skeptic; Lens B = maintainability + coverage completeness. Their packets are identical except the single Assigned perspective: line; the instances are dispatched in parallel and synthesized into one verdict. The named THOROUGH trigger selects only escalated platform diversity. The active platform supplies the diversity leg. If that leg is unavailable, default mode uses two independent same-model instances and records the reason; an explicit caller demand for diversity is strict mode and transitions to PAUSED instead of falling back. The verifier remains outside this pair contract.

Confirming-verifier reuse: when this skill runs as the final gate inside ralph or ultrawork and the caller already completed the required independent confirming verifier pass for the same final claim, do not dispatch a second verifier when the pass ran as an independent dispatch (never the maker) after the selected code-review stage and no file, dependency, or evidence changed after that pass [V1, V5]. On the no-fix path, the review and verifier evidence bind to the reviewed revision. On the fix path, reuse requires review evidence bound to the reviewed revision plus verifier evidence bound to the fixed revision, with the verifier dispatched after the fix manifest was recorded. Record the reused pass as a reference to the caller's ledger entry and its revision binding under the carve-out. This reuse satisfies only the verifier-dispatch expectation: every Required Gate step still executes in full, and this clause never licenses skipping this skill itself. Dispatch a fresh verifier when evidence changed after the caller's pass or when no compliant pass exists.

Confirming code-reviewer reuse: when this skill runs as the final gate inside ralph or ultrawork and the caller already completed the required single perspective-diverse code-reviewer round for the same final claim, do not dispatch a second code-reviewer. On the no-fix path, reuse requires review evidence bound to the reviewed revision with no file, dependency, or evidence change since that review. On the fix path, reuse requires that review binding plus verifier evidence bound to the fixed revision, with no file, dependency, or evidence change after the verifier pass. Record the reused review as a reference to the caller's ledger entry and its revision binding. Dispatch a fresh code-reviewer only when this skill runs standalone (not nested) or no compliant code-review exists for the claim.

Output

Return: claim verified; evidence used; commands or inspections performed; acceptance criteria status; acceptance-to-evidence mapping; contract surface and baseline guard status; risk check and completion claim; validation check when applicable; skipped checks and reason; residual risk.

Next Skill Handoff

None — this is the final evidence gate [V8]. Return the result to the caller (ralph, ultrawork, or direct invocation). Do not chain to another workflow skill.

Source: docs/platforms/claude-code-verification-before-completion.md

Verification Before Completion Claude Code Adapter

<ADAPTER_CONTRACT> This adapter binds the Verification Before Completion core to Claude Code. The core owns every semantic decision; this file owns only host invocation and lifecycle mechanics. If they conflict, the core wins. The generated core plus this adapter is sufficient: longer platform, shared, and agent documents are optional maintenance context, never a runtime prerequisite. </ADAPTER_CONTRACT>

Role Dispatch

Dispatch verifier and risk-gated code-reviewer through the exposed Task, Agent, Workflow agent(), or subagent primitive with the plugin agents (oh-no-harness:<agent>; manual mention @agent-oh-no-harness:<agent>). Dispatch is trigger-loaded — dispatch only after the core's trigger fires. Pass the core-defined role envelope and verification delta unchanged. A notification, timeout, or empty wait result is not a final status; capture the result, then close or clean up the completed subagent when the host exposes that mechanism. If a plugin-scoped agent is unavailable, embed the matching agents/<agent>.md prompt into the available subagent mechanism. With no subagent primitive, verify inline only when the core does not require an independent audit; otherwise report the dispatch-unavailable blocker so the caller remains blocked/PAUSED.

Model Diversity Pair

For any dispatched code-reviewer pair (every dispatched review), dispatch two same-role instances in parallel and synthesize one verdict. Both legs MUST be requested in a single batch: issue both subagent tool calls in the same assistant turn (or with Background: yes for both) BEFORE waiting on either result; a serial dispatch-wait-dispatch sequence is not a valid pair. The two legs' packet bodies MUST be identical except the single Assigned perspective: line (Lens A on the primary leg, Lens B on the diversity leg); leg identity (primary vs diversity) is carried ONLY by the host dispatch metadata (the description field and the model override), never inside the packet text. Read the role's declared stored primary and the validated secondary top-tier model from the session <OH_NO_MODEL_DIVERSITY> block.

• model-diversity-pair: the primary leg is dispatched without a model override and therefore uses the concrete declared-frontmatter primary; the diversity leg uses an explicit NATIVE model override for the validated secondary. The primary must not be host-default, and the secondary must differ from the declared stored primary.
• same-model-parallel-fallback: when no valid diversity configuration exists, the declared primary cannot be applied, or the secondary override fails in default mode, dispatch two independent same-model code-reviewer instances and record the reason.
• require-model-diversity: an explicit caller demand for diversity is strict; if the diversity leg is unavailable or fails, transition to PAUSED. Do not substitute the same-model fallback.

The verifier is never paired.