---
name: project-verification-before-completion
description: Use when about to claim PRD Plugin work is complete, fixed, implemented, healthy, passing, or ready to commit.
---

# Project Verification Before Completion

Adapted from Superpowers by Jesse Vincent, MIT licensed:
https://github.com/obra/superpowers

Use this skill to verify work before making completion claims, with PRD Plugin
evidence and state consistency requirements.

## Iron Law

```text
NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
```

PRD Plugin IDs are non-negotiable. Verification must support the durable IDs
that will be marked complete, implemented, healthy, or resolved.

## Gate

Before saying work is complete, fixed, passing, implemented, healthy, or ready:

Read `verification.test_scope` before choosing the verification breadth.

Plan and run `engineering.verify` when enabled. Its receipt owns the
verification plan, diff check, state consistency, and gate. Read every result
and apply the evidence rules below; do not rerun identical passing mechanics
merely to make them "fresh" in the same change fingerprint.

1. Identify the exact command or artifact that proves the claim.
2. Build and execute the current verification plan with
   `python .prd_plugin/scripts/prd_test_scope.py --repo-root . --execute`.
   Fresh means evidence matches the current change fingerprint and plan inputs;
   it does not mean rerunning an identical passing command again in one session.
3. For `impact_scoped`, AI-Collab supplies impact neighbours; the deterministic
   PRD executor maps exact and nearby files to tests and runs argv-only configured
   or detected commands. Unmapped, degraded, over-broad, or failed selection
   widens to full verification.
4. Run the project's full verification command when the plan says `full`.
   Release, core, excessive, unavailable, degraded, or unmapped scopes must
   widen or fall back to full. `none` is valid only when no files changed and
   the claim itself needs no execution.
5. Read every selected command's output and exit code.
6. Map the output to affected `REQ-*`, `IMP-TASK-*`, `EV-*`, `HLT-*`, `TRK-*`,
   `CHG-*`, or artifact IDs.
7. Update durable state only if the evidence supports it.
8. State the result with the plan strategy, commands, and outcomes.

## Scope The Tests To What You Changed

**Full tests only before a commit. Scoped tests for everything else.**

Running the whole suite after every edit does not verify more - it re-tests code
you did not touch, and a long command with no output reads as a hung session.
The verification plan above already selects the focused commands; use them
mid-work and keep the full set for the run immediately before a commit. A
version bump alone needs no re-run: rewriting version strings does not change
the code under test.

`hooks.test_scope_guard.enabled` (on by default) enforces this at PreToolUse. A
whole-suite command is blocked while nothing is staged and the change set is
narrow, and the refusal names the scoped command to run instead. It allows the
run when something is staged, when a core path moved, when the change is broad,
or when no scoped command can be derived - and it announces every full run
before it starts, saying whether it is the pre-commit one. `PRD_FULL_SUITE=1` in
the command is the explicit override.

## PRD Plugin Verification Set

Use the smallest sufficient set. Do not infer a universal test command from the
repository language; use the repository's configured focused/full commands and
the current verification plan:

- `python .prd_plugin/scripts/prd_test_scope.py --repo-root .`
- The focused or full project commands selected by that plan
- If installed: `python .prd_plugin/scripts/state_consistency_check.py --repo-root .`
- If installed: `python .prd_plugin/scripts/request_report.py --config .prd_plugin/config.json`
- If installed: `python .prd_plugin/scripts/message_check.py --repo-root . --config .prd_plugin/config.json`
- If installed: `python .prd_plugin/scripts/prd_doctor.py --repo-root .`

Do not run `gap_audit.py`, `release_check.py`, `local_workflow_check.py`,
or `version_advice.py` in this repo. Those are hub-only scripts.

## Evidence And State Hooks

- Completion claims for planned work should cite or create `EV-*`.
- Implemented requests must include `graduated_to`.
- Findings parked during the work (unrelated bugs noticed while debugging)
  must be filed as `REQ-*` and visible before the completion claim. Closing
  an episode is the moment to loop back to what was set aside, not the moment
  it gets forgotten.
- Resolved health findings need validation evidence or an explicit residual
  risk.
- Evidence/session summaries must not claim missing `MEM-*`, `TRK-*`, `CHG-*`,
  `OBS-*`, or `SES-*` records.
- Do not commit generated local-only files under `.prd_plugin/local/` or
  `request-report/` unless the repo policy says they are durable artifacts.
- When a significant piece of work closes and produced durable domain/codebase
  knowledge (an as-built understanding, a root cause, a settled decision, a
  measured number), ingest it into the repo's `wiki/` via `project-llm-wiki`
  unless `knowledge.llm_wiki.enabled` is `false`. The wiki is where the next agent
  looks before re-deriving it.

When the `prd-plugin` MCP server is wired, record the proof with
`prd_record_evidence` and close the goal with `prd_close_goal` (it refuses to
close without evidence or an explicit no-evidence reason), then pre-flight with
`prd_validate` before committing.

## Tool Parity Check

Before claiming an agent-facing feature complete, verify tool parity: the
exposing tool exists, is registered in the project's tool catalog, and is
reachable (invoke it or run its tests). A feature with no agent-invocable
surface must record its exemption rationale instead of silently skipping.

## Staleness Coverage

Verification must include stale-state checks for the IDs behind the completion
claim. If `REQ-*`, `TRK-*`, `HLT-*`, request transport, scheduler state, or
evidence is stale, report that status instead of claiming completion.

## Red Flags

- "Should pass" without command output.
- Claiming success from an earlier run.
- Trusting another agent's report without checking files or output.
- Skipping `state_consistency_check.py` for evidence/session/registry changes.
- Marking `REQ-*` implemented without `graduated_to` and verification.
- Closing work with findings parked mid-debug that were never filed.