completion-audit

name

completion-audit

description

Mandatory completion audit gate. Run this skill ONCE as the final gate task before declaring all work complete. Audits whether implementation and verification evidence are sufficient for the plan's stated purpose. Default mode is a self-audit table by the main session; a fresh completion-auditor subagent is dispatched only when escalation conditions fire. Do NOT run per-task — run only at the final gate. Skipping the completion audit is the #1 cause of false completion claims.

Completion Audit

Overview

A completion claim without audit is a lie, not an optimization.

Core principle: Evidence before claims, always. But evidence is gathered during implementation, not re-gathered at the gate.

Mode selection: The default is a self-audit — the main session cross-checks every Completion Criteria item against the collected evidence and presents the table to the user. A fresh completion-auditor subagent is dispatched only when an escalation condition fires (Step 3). This keeps the evidence discipline while removing a subagent round-trip that, measured over 18 gate executions, passed 94% of the time and never caught a functional defect — the discipline lives in /impl's per-task raw-evidence rule, which is unchanged.

Completion Audit Workflow

This skill runs ONCE at the final gate task, after all implementation tasks are complete.

Step 1: Evidence Collection

Performed by the main session (the implementer):

1. Read the plan file and extract:
   • Plan Purpose (Background/Context section)
   • Completion Criteria section
2. For each completed implementation task, collect:
   • What was implemented (files changed, behaviors added/modified)
   • What was verified during the task (commands run, raw output observed, results)
3. Run git diff --name-only against the baseline SHA to get the full changed file list

Anti-curation rules (these are mandatory):

• The Verified field for each task MUST contain raw command output (exit codes, test output, actual stdout/stderr)
• Summaries like "tests pass", "looks correct", "works as expected" are PROHIBITED — paste the actual output
• If a verification command was not executed during the task, state Result: 未実施 explicitly
• Do NOT paraphrase, rephrase, or selectively quote output

Evidence format:

## Plan Purpose
[Plan's Background/Context section, verbatim]

## Completion Criteria
[Plan's Completion Criteria section, verbatim]

## Task Evidence

### Task 1: [subject]
- **Implemented**: [files changed, behaviors added/modified]
- **Verified**: [exact commands run and their raw output]
- **Result**: [PASS/FAIL/未実施]

### Task 2: [subject]
...

## Changed Files
[git diff --name-only output]

Verifier tag handling (mandatory when the plan uses /plan tags):

Each Completion Criteria item is tagged by /plan Phase 4 Step 8 with one of:

• [file-state] — verifiable by Read / Grep / Glob
• [orchestrator-only] — required host access the auditor's sandbox may lack; main session pre-runs and embeds verbatim output in evidence
• [outcome] — circular by design, references post-audit state (e.g., /subagent-review returns PASS). Evaluated AFTER /completion-audit returns PASS, so no evidence exists at audit time

When building the evidence document, preserve these tags verbatim from the plan. Both audit modes exclude [outcome]-tagged items from the verdict: the self-audit marks them NOT GATING (Step 2), and the escalated auditor prompt (Step 3) must explicitly instruct the subagent to EXCLUDE them — otherwise the audit deadlocks (auditor demands evidence for [outcome] items that by design cannot exist yet, forcing a FAIL verdict, which blocks running the thing the [outcome] item references).

Step 2: Self-Audit (default)

The main session performs the audit itself. For every Completion Criteria item, cross-check it against the Task Evidence and emit a table to the user:

## Self-Audit

| # | Criterion | Tag | Evidence (task # / command) | Verdict |
|---|-----------|-----|------------------------------|---------|
| 1 | <criterion text> | [file-state] | Task 2: `deno test …` exit 0 | PASS |
| 2 | <criterion text> | [orchestrator-only] | Task 3: raw output embedded | PASS |
| 3 | <criterion text> | [outcome] | — (excluded: circular by design) | NOT GATING |
| 4 | <criterion text> | [file-state] | 未実施 | FAIL |

VERIFIED: PASS (self-audit)   ← or VERIFIED: FAIL (self-audit)

Rules:

• [outcome]-tagged items are excluded from the verdict (NOT GATING) — same protocol as the subagent path
• [orchestrator-only] items waived by explicit user decision count as satisfied (BLOCKED BY USER)
• The verdict is VERIFIED: PASS (self-audit) only when every gating item is PASS. Any FAIL or 未実施 on a gating item → VERIFIED: FAIL (self-audit): address the gap (run the missing verification), then redo this step
• The Evidence column must point at concrete raw output already captured in task metadata.evidence — do not paraphrase results into the table; the table locates evidence, it does not restate it

If no escalation condition (Step 3) fires, VERIFIED: PASS (self-audit) completes this skill's half of the gate — proceed to Step 4.

Step 3: Escalation — Spawn Completion Auditor (conditional)

Dispatch a fresh completion-auditor subagent only when at least one of these conditions holds:

1. Plan complexity is large or xl (from the plan's ## Plan ready block or plan body)
2. Any gating criterion's evidence is 未実施, missing, or lacks raw command output after the self-audit fix loop (i.e., the self-audit cannot honestly reach PASS)
3. The user explicitly requests a subagent audit

When escalating, dispatch via the Agent tool:

Agent tool:
  subagent_type: "completion-auditor"
  prompt: [include the evidence document from Step 1 + the Audit Protocol Clarification below]

Audit Protocol Clarification (mandatory — prepend to every auditor dispatch):

## Audit Protocol Clarification

1. `[outcome]`-tagged Completion Criteria items are CIRCULAR BY DESIGN — they describe post-audit
   state (e.g., `/subagent-review returns PASS`) that only becomes true AFTER this audit returns PASS.
   Do NOT demand evidence for `[outcome]` items. Exclude them from the verdict determination
   (treat as NOT GATING). If you require evidence for an `[outcome]` item, the workflow deadlocks.

2. `[orchestrator-only]` items waived by explicit user decision (documented in evidence as
   "USER WAIVED" or equivalent) count as satisfied via the "Requires User Confirmation"
   alternative pathway. Treat as BLOCKED BY USER (legitimate skip), not as MISSING EVIDENCE.

3. Evaluate only `[file-state]` and non-waived `[orchestrator-only]` items for PASS/FAIL. All
   other items (outcome, user-waived) are excluded from the verdict.

Pass to the auditor:

• The Audit Protocol Clarification above (verbatim)
• The complete evidence document from Step 1

Do NOT pass: full implementation history, your own assessment of quality, or results from prior audit attempts.

Handling the auditor result (escalation path only):

Relay the audit findings to the user. The auditor's output is returned as an Agent tool result, which is not visible to the user. You MUST relay the auditor's complete findings — per-criterion assessments, dimension summaries, and verdict — before taking any action. Display the auditor's output in full; do not paraphrase or summarize into "audit passed" or similar.

On re-runs (after FAIL), relay the new audit findings each time.

Then take action based on the verdict:

Result	Action
VERIFIED: PASS	Evidence audit passed. Proceed to Step 4 — /subagent-review is the next gate before completion can be declared
VERIFIED: FAIL	Read the auditor's gap analysis. Address the specific gaps (run missing verifications, fix issues), then re-run from Step 1 with a fresh subagent
No VERIFIED line	Treat as FAIL
3 consecutive FAILs	Report the final audit result to the user and let them decide. Do not mark the task complete

Never retry with the same subagent — always spawn fresh.

Step 4: Hand off to /subagent-review

VERIFIED: PASS — whether from the self-audit (Step 2) or the escalated subagent audit (Step 3) — authorizes only the evidence-sufficiency half of the final gate — it does not by itself authorize a completion claim. The current /impl final gate requires /subagent-review to also return PASS against the aggregated diff before all work may be declared complete (see ~/.claude/skills/impl/SKILL.md Final gate section).

After VERIFIED: PASS:

1. Hand off to /subagent-review (invoked by /impl automatically; manually invoke if running /completion-audit standalone).
2. Only after /subagent-review returns PASS (no open MUST_FIX) may completion be declared.

Standalone invocation note: when /completion-audit is run outside /impl, VERIFIED: PASS indicates evidence is sufficient — the user is responsible for invoking /subagent-review (or accepting the partial-gate result explicitly) before claiming completion.

Red Flags — STOP

If you catch yourself in any of these thought patterns, return to the Completion Audit Workflow:

• About to use "should work", "probably fixed", or "seems to pass"
• About to write "done" or "complete" before running the completion audit
• "It worked before, so it still works"
• "I changed the code, so the bug is fixed"
• "I wrote the test, so it's fine" (without running it)

Common Rationalizations

• "No need to audit" → Confidence is not a substitute for audit
• "It's a simple change" → Simple changes can still introduce bugs
• "Each task was verified individually, so the whole is fine" → Individual task verification does not guarantee goal achievement
• "Tests pass, so we're done" → Tests passing is necessary but not sufficient — does the outcome match the purpose?