---
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. See
`.prd_plugin/method/completion-gate.md` for the shared completion rule,
`.prd_plugin/method/state-validation.md` for the state-validation procedure, and
`.prd_plugin/method/grounding.md` for the no-hallucination grounding rules.

## 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 the current verification plan with
   `python scripts/prd_test_scope.py --repo-root . --execute` in this hub, or
   `python .prd_plugin/scripts/prd_test_scope.py --repo-root . --execute` downstream.
   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.**

The full suite here is ~1160 tests and several minutes. Running it 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. One agent ran it six times in a
session for changes of two or three files each.

- **Mid-work:** run the test modules covering the files you changed. Map each
  changed source file to its module: `scripts/prd_install.py` →
  `python -m unittest tests.test_prd_install -q`. Several modules go in one
  command.
- **Before a commit:** run the full suite once. This is the sanctioned full run.
- **A version bump alone needs no re-run.** Rewriting version strings does not
  change the code under test; the previous green run still stands.

`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 (a commit is imminent), 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, and prefer the full set for plugin-wide work:

- `python -m unittest tests.test_<module> -q` — the scoped mid-work default
- `python -m unittest discover -s tests -v` — before a commit, or plugin-wide work
- `python scripts/local_workflow_check.py`
- `python scripts/state_consistency_check.py --repo-root .`
- `python scripts/request_report.py --config .prd_plugin/config.json`
- `python scripts/message_check.py --repo-root . --config .prd_plugin/config.json`
- `python scripts/prd_doctor.py --repo-root .`
- `python scripts/gap_audit.py --target-version <version>` before version bumps
- `python scripts/release_check.py --output request-report/release-hygiene.md`

## 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 tool-surface catalog and the
feature coverage map (`tool_capabilities`), and is reachable (invoke it or
run its tests). `python scripts/feature_skill_audit.py` must report no tool
parity findings. A feature with no agent-invocable surface must carry its
`tool_exemption` rationale in the coverage map.

## Staleness Coverage

Apply the shared policy in `.prd_plugin/method/staleness-rules.md`.


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.