| name | verify-and-revise |
| description | Run a bounded producer-verifier revision loop for one explicitly authorized artifact against a fixed acceptance rubric or oracle. Use when an artifact needs repeated evidence-backed revision with actionable feedback, an attempt ledger, minimal coherent changes, and clear pass, retry-cap, plateau, authority, and conflict stopping rules. |
| license | MIT |
Verify and Revise
Improve one explicitly authorized candidate artifact through a bounded,
evidence-backed producer/verifier loop. The acceptance rubric or oracle is
fixed for the run; revisions may satisfy it but cannot redefine it. Label the
candidate an Accepted Artifact only after terminal pass evidence.
Establish the revision contract
Before changing the artifact, record:
Candidate artifact identity and authorized mutable scope:
Acceptance rubric or authoritative oracle:
Producer:
Verifier:
Baseline result and evidence:
Maximum attempts:
Repeated-evidence / plateau threshold:
Checkpoint and overlap boundary:
Final evidence:
The artifact may be code, a document, a configuration, a plan, or another
bounded deliverable. The rubric must state observable pass conditions, not a
general request to “make it better.” Confirm that its verifier can inspect the
same artifact identity the producer changed.
Use a separate producer and verifier role logically, even when one person or
agent performs both sequentially: verify the actual candidate after producing
it, and write feedback from the rubric rather than from the producer's intent.
This skill authorizes mutation only inside the stated artifact scope when the
user authorized that mutation. It grants no authority for adjacent files,
dependencies, commits, pushes, deployments, publication, messages, external
writes, or changes to the rubric or oracle.
Keep an attempt ledger
Maintain the authoritative run state in the task unless the user approved a
durable location:
attempt | artifact identity | rubric version | verifier evidence fingerprint
failed criterion | actionable feedback | smallest revision | result | decision
An evidence fingerprint identifies unchanged verifier evidence relevant to the
failed criterion. Read the ledger before each attempt. It prevents cycling on
the same feedback or claiming a changed result without changed evidence.
Run one revision cycle
- Preserve the rubric, oracle, and candidate identity from the contract.
- Have the verifier evaluate the current artifact and return each failed
criterion, evidence, and smallest known distinguishing observation.
- Stop with
pass when all acceptance criteria have evidence.
- Translate one or more related failed criteria into actionable feedback:
what is false, where it is observable, and what constraint a revision must
preserve.
- Produce the smallest coherent revision that addresses that feedback inside
the authorized scope.
- Verify the revised artifact against the unchanged rubric or oracle.
- Record the result, evidence fingerprint, decision, and budget.
- Evaluate every stopping rule before another revision.
A revision may address several criteria only when one coherent change is needed
for them. Keep unrelated cleanup, speculative redesign, and scope expansion out
of the cycle. A passing producer claim is not verification evidence.
Stop and hand off precisely
Stop immediately on pass, retry-cap exhaustion, repeated unchanged evidence,
an oracle that cannot run or cannot identify the candidate, a blocker, new
authority, or an overlapping user edit in the checkpoint boundary. Preserve
the artifact and evidence; do not overwrite user changes or roll back beyond
the loop-owned revision.
On passed, emit the Accepted Artifact identity, fixed rubric/oracle, all
attempts and decisions, and terminal verifier evidence. On stopped or
blocked, report the last candidate identity, its final verifier evidence,
and the smallest next decision; do not label it accepted. Completion requires
terminal pass evidence, not a producer's statement or an exhausted attempt
count.
Boundary with adjacent skills
design-verification-strategy designs a proof strategy and oracle set; use
it first if the acceptance rubric is missing or contested.hill-climbing optimizes a numeric metric with a behavioral guard; use it
when keeping/discarding experiments is the primary decision.tdd is a test-first development practice, not a general artifact
producer/verifier orchestrator.code-review assesses a change against a spec and standards; use it when
review findings, rather than accepting one target artifact, are wanted.
This skill does not invoke those companions or copy their procedures.
Examples
Revise this installation guide until it passes the supplied seven-item
accessibility and accuracy rubric. You may edit only docs/install.md; stop
after three failed revisions.
Revise the generated schema only inside schemas/customer.json until the fixed
validator reports success. Do not change the validator or adjacent sources.
Counterexamples
- “Improve the whole product until reviewers are happy” has no bounded artifact
or fixed oracle; establish both before using this skill.
- “Make the test pass by changing its expectations” weakens the rubric and is
outside this loop's authority.
