lykAntonio/proof-of-done

Proof of Done

Treat completion as a claim that needs evidence, not as a statement to repeat. Help the user spend attention on product judgment by taking care of systematic, mechanical verification.

Choose the mode

Choose from the user's timing and request:

• Contract mode — work has not started, or the user asks for acceptance criteria or a Definition of Done. Create ACCEPTANCE.md.
• Audit mode — an acceptance contract already exists and implementation is ready. Audit against that contract.
• Recovery audit — implementation is already finished but no contract exists. Derive criteria from the original task, label them as post-hoc, and audit them without pretending they were agreed in advance.

If the user only asks “test the change” after an agent finishes, use Recovery audit. Do not force a preliminary interview when the task, repository, and requested output are already discoverable.

Non-negotiable boundaries

• Work independently from the implementing agent's completion claim. Read the original task, acceptance contract if present, repository state, and resulting artifacts; do not use implementation reasoning as proof.
• Do not modify source code, tests, fixtures, configuration, lockfiles, snapshots, or user data during an audit. Build artifacts and temporary files created by established quality commands are acceptable; report them.
• Do not install dependencies, deploy, publish, run migrations, contact real external services, or use production credentials without explicit approval.
• Inspect a command before running it. Skip commands with destructive or unclear effects and mark the affected criterion UNKNOWN.
• Do not convert missing evidence into a pass. The burden of proof is on PASS.
• Do not fix discovered problems unless the user separately asks for fixes.

Status vocabulary

Use exactly one status per acceptance item:

• PASS — direct evidence demonstrates the criterion.
• FAIL — direct evidence contradicts the criterion or reproduces a defect.
• UNKNOWN — the environment, permissions, dependencies, or safety boundary prevent a reliable verdict.
• HUMAN_REVIEW — the criterion is primarily subjective or requires business judgment.

Do not use partial credit. Split broad criteria into smaller atomic items instead.

Contract mode

1. Read the original task and any referenced issue, specification, screenshots, or files.
2. Preserve explicit obligations. Do not silently weaken words such as “only”, “must”, “all”, “never”, supported platforms, roles, formats, or error behavior.
3. Split obligations into atomic acceptance items with stable IDs: AC-01, AC-02, and so on.
4. Add a small number of derived checks only when they protect an obvious failure mode. Label their source Derived risk, so they cannot be mistaken for user requirements.
5. Classify each item as functional, error handling, security/permissions, compatibility, regression, artifact/documentation, or human judgment.
6. Define what evidence would be sufficient before implementation starts.
7. Add requirement traceability and keep unresolved decisions explicit.
8. Write ACCEPTANCE.md using the compact format in references/acceptance-contract.md.
9. Validate it with:

python3 <skill-dir>/scripts/validate_contract.py <contract-path>

Ask the user only about ambiguities that would materially change implementation or acceptance. Do not block on minor wording choices.

Audit and recovery-audit workflow

1. Establish the evidence basis

Read, in this order:

1. Original task or issue.
2. ACCEPTANCE.md, if present.
3. Repository instructions such as AGENTS.md.
4. Relevant changed files and diff, when available.
5. Test, build, lint, and type-check configuration.

If the original task cannot be found, ask for it. A diff alone cannot prove that the intended task is complete.

In Recovery audit, state prominently that criteria were derived after implementation and therefore provide weaker protection against goalpost drift.

2. Build the obligation ledger

Map every explicit requirement to one or more atomic acceptance items. Preserve important nouns, roles, limits, formats, and negative requirements.

Read references/risk-catalog.md and select only the risks relevant to the current task. Avoid dumping a generic checklist into every audit.

Split a requirement only when its parts can receive different verdicts or need meaningfully different evidence. Excessive splitting hides the decision inside repetitive prose.

3. Discover safe quality gates

Run:

python3 <skill-dir>/scripts/discover_checks.py <repository-root>

The script only recommends commands; it does not execute them. Inspect the recommended manifest entries before deciding what is safe.

Prefer existing project commands over invented one-off checks. Typical safe candidates include unit tests, targeted integration tests, static analysis, type checks, and local builds. A green existing test suite is evidence about covered behavior, not proof that every acceptance item is covered.

Read references/project-routing.md for project-specific verification choices.

4. Verify adversarially

For each acceptance item:

1. Identify the cheapest reliable verification method.
2. Look for both confirming and disconfirming evidence.
3. For permissions, negative requirements, error handling, idempotency, data loss, and overwrite behavior, attempt the forbidden or failure path—not only the happy path.
4. Prefer executable evidence when safe. Otherwise cite exact code, configuration, artifact, or documentation locations.
5. Record the command, exit status, relevant output, and location of supporting evidence.
6. Compare test coverage with the requirement. Call out requirements that have no corresponding test or executable check.

Do not claim a defect solely from a suspicious code pattern when a safe executable check could confirm it. Conversely, do not run unsafe commands merely to convert UNKNOWN into a verdict.

5. Produce the report

Write PROOF_OF_DONE.md, or the exact output path requested by the user, using references/report-template.md.

Default to the compact acceptance table. For a small audit, aim for a report that can be scanned in two minutes and is usually under 1,200 words. Put decisive evidence in the table; add detail only when a failure genuinely needs a longer reproduction.

Each acceptance row must contain the item ID, status, requirement/source, verification and evidence, and reproduction method. Keep the executive verdict to four lines. Do not repeat the same command result under every item; give it a command ID such as C1 and reference that ID.

After writing the report, validate its structure:

python3 <skill-dir>/scripts/validate_report.py <report-path>

Fix structural validation failures in the report. Do not alter project code.

Evidence rules

Read references/evidence-rules.md before assigning final statuses. In particular:

• File existence alone rarely proves correct behavior.
• Source inspection can prove that a guard is absent, but avoid claiming runtime behavior that the inspected path does not establish.
• Test names are not evidence that tests ran.
• A command described but not executed must be labeled as a proposed verification, not an executed result.
• Existing passing tests do not cover requirements they never assert.

Final handoff

Tell the user:

• Overall result and counts by status.
• The highest-risk failures first.
• Which findings have executable evidence.
• What remains unknown or needs human review.
• Whether the audit was contract-based or post-hoc.

Avoid a generic quality score. Status counts and evidence are more honest and actionable.