pc-verification-before-completion

Imported from yknothing/prodcraft (skills/cross-cutting/pc-verification-before-completion/SKILL.md). Install upstream with npx skills add yknothing/prodcraft --skill pc-verification-before-completion. Copyright stays with the author.

Verification Before Completion

Evidence before claims. No completion, fix, or readiness statement without fresh verification.

Context

pc-verification-before-completion is the cross-cutting gate that protects Prodcraft from false completion claims.

See context and anti-pattern notes.

Inputs

I/O contract notes define required inputs and authority.

Process

Step 1: Name the Claim Precisely

State exactly what is about to be claimed:

• "the fix works"
• "all tests pass"
• "this phase is complete"
• "the release is ready to ship"
• "the incident is resolved"

If the claim is vague, split it into smaller claims. Verification is only meaningful when the claim is concrete.

Step 2: Identify the Fresh Evidence Required

For each claim, name the proof needed now:

• command output
• failing-then-passing regression evidence
• artifact presence and handoff checks
• quality gate checklist
• rollout or recovery verification

Do not rely on stale runs, partial checks, or "it should still be green."

Use this quick reference before moving on:

Step 3: Run the Verification Now

Execute the relevant verification in the current message or session:

• run the full command, not a weaker proxy
• read the actual output and exit status
• confirm the expected artifact or file exists
• confirm the current phase gate is satisfied
• note any unverified areas explicitly

For fast-track work, run the narrowest command set that still proves the claim. "Fast" changes the scope of proof, not the need for proof. NEVER assume a file was modified or a task was completed based on context or conversational history. If you cannot see the change via a diff, cat, or directory listing, the evidence is missing and the verification MUST fail. Proof cannot be hallucinated or waived just because a fix is small.

Step 4: Check Artifact and Handoff Integrity

Before making the claim, verify that:

• required phase outputs exist and are accessible
• any schema-backed artifact still satisfies its contract when applicable
• handoff context is explicit enough for the next skill or operator
• any skipped checks are logged as real gaps, not implied away

When producing a repository artifact instance, store it under the governed project's .prodcraft/artifacts/ directory when that directory exists. If the project has no .prodcraft/ convention yet, write the instance in the nearest existing evidence or handoff directory and record that path in the handoff.

For a verification-record instance, run:

python scripts/validate_prodcraft.py --artifact-instance <path-to-verification-record.json>

When the project has opted into the strict execution loop, generic artifact validation is not completion authority. Bind the accepted verification record and its evidence snapshots into the current completion attempt, then run:

python scripts/validate_prodcraft.py \
  --authorize-execution-state .prodcraft/artifacts/<work_id>/execution-state.json \
  --approved-route-digest sha256:<operator-pinned-route-digest> \
  --approved-completion-digest sha256:<operator-pinned-completion-digest>

Only terminal-authorized permits an unqualified route-level completion claim. gate-authorized is non-terminal progress authority. A historical, non-canonical, missing-pin, stale-work, or structurally-valid-only result blocks the claim. Run the terminal command once without the completion pin to obtain a non-authoritative candidate digest, review the frozen verification commitment and terminal records, then supply the approved digest from outside the writable bundle.

If the verification reveals a gap, do not translate it into optimistic language. State the actual status.

Step 5: Record the Result Honestly

Produce a verification-record that states:

• the exact claim tested
• the commands or checks run
• what passed
• what failed
• what remains unverified
• whether the claim may now be made without qualification

When the Prodcraft source repository (or a repository that vendored its validators) is available, validate the structured record instead of eyeballing it:

python scripts/validate_prodcraft.py --artifact-instance <verification-record file>

This checks the schema contract plus the completion-claim bindings (evidence freshness against the recorded work state). Outside that context, check the record manually against the verification-record.v1 fields and say so explicitly.

Only after this step may the workflow say the work is complete, fixed, passing, or ready for handoff.

Outputs

Produce only declared outputs at their documented quality boundary.

Quality Gate

• The completion claim is explicit rather than implied
• Fresh verification was run for the actual claim, not a nearby proxy
• Relevant artifacts and handoff requirements were checked
• Failures, skips, or unknowns are stated plainly
• The final wording matches the evidence instead of the hoped-for result
• When strict mode is active, the canonical state returns terminal-authorized against both operator pins and the live worktree