Proof It Works
This skill owns one decision: whether work may be called done. It is a hard gate, not advice.
1. Core law: Done = Proven
- A claim is not evidence. Only a reproducible artifact a second agent can inspect counts.
- You may not say done, fixed, passing, or shipped while any required gate item in section 6 is missing.
- "Should work", "looks right", "theoretically fine", and "compiles" are not completion states.
- If proof is impossible, declare UNAVAILABLE/BLOCKED (section 7) — never PASS. A written user waiver may close a FAIL as FAIL-WAIVED (section 7). A machine-untestable dimension may stay PENDING USER and close as PASS-BY-USER on user approval (section 7). These three —
FAIL-WAIVED,PENDING USER,PASS-BY-USER— are the only non-machine-evidence exits; none of them is PASS. - Evidence must come from the working tree and the change commit named in the report (section 3,
Change ref); stale artifacts are invalid. - This skill gates only work with a runtime surface or a design deliverable. For that work its minimum evidence set (one positive + one reverse) replaces, not stacks on, any lighter check. Work with no runtime surface is out of scope and this skill yields entirely. It does not override a delivery the user has already approved as minimal.
2. Evidence levels
Three levels in strict order: Claim (verbal or reasoning, zero evidence) < Artifact (a real raw artifact file from this task's surface) < Artifact + reverse case. The gate accepts only the last two; which one an item needs is set by the selected profile's gate items, not by a global rule. A Claim never supports PASS, and no item may be labeled above what it actually is.
3. Binding / Task Binding
- At the top of
report.md, quote verbatim the sentence from the user's request that defines the acceptance target — an instruction such as "change X to Y and prove it" counts; it need not state that the work is done. Label itAcceptance target (user verbatim). Only if the request defines no acceptance target at all (it never says what "done" must look like), say so in one line, ask the user to state one, and stop — there is nothing to gate. The evidence levelClaimin section 2 is a separate concept and keeps its name. Change ref(report header) = the commit that contains the change under test — not the commit that adds this report, and not necessarily HEAD. Without git, usesha256 of changed files + file listinstead of a hash. After the report is committed HEAD moves forward; that is normal, and the verifier judges byChange ref, not by HEAD.Working tree(report header) is free text, not a two-value enum, e.g.tracked clean; .proof/ untracked.- Declare the files / functions / routes / components this change touched, taken from the current diff.
- Every selected profile must have at least one evidence item that lands on this diff (executes or inspects a touched path). Evidence that touches nothing in the diff = FAIL, even if all artifacts exist.
- A DESIGN baseline must have an external source (section 6, proof-profiles.md); an untraceable baseline is a
Claimand fails its gate item.
4. Select proof profile(s)
Pick the profile whose one-line test best fits the user's acceptance-target sentence; a task can be DESIGN and FEATURE at once and must then satisfy both. If no profile matches, say so in one line and stop — do not force a profile onto a change with no runtime surface.
| Profile | One-line test | Detail |
|---|---|---|
| DESIGN | You produced a spec, layout, interaction, architecture, or contract that must be shown implemented, not just proposed. | references/proof-profiles.md |
| FEATURE | You changed runtime behavior and must show it works and that bad input is rejected. | references/proof-profiles.md |
| DATAFLOW | A value crosses multiple stages (entry, transform, persistence, exit) and each hop must be shown. | references/proof-profiles.md |
- "Did my design get implemented" -> DESIGN. "Does this work" -> FEATURE. "Where did the data go / is it persisted" -> DATAFLOW.
5. Execution flow
Run in order. Do not skip or reorder.
- Create
.proof/<task-name>/in the repo (short kebab-case name). An artifact is not proof until it is a file here. - Write 3-7 acceptance assertions in
report.mdBEFORE collecting evidence. Use the 8 columnsid | assertion | expected | pass criterion (checkable) | changed path (file:function/route) | level required | evidence file | depends on. Ban "looks correct", "seems fine", "works as expected"; use checkable conditions like "HTTP 200 with body.field X = Y", "rect width = 120px", "invalid token returns 401".expectedis the predicted result filled BEFORE any evidence (e.g.401 + BAD_CREDENTIALS,rect width 240px); FEATURE/DATAFLOW must fill it on every row, DESIGN may writen/a. Record the registration time in the report header asExpected registered (UTC): <time>— preregistration is self-declared; no hash or on-disk ritual.expectedandpass criterionare two expressions of one condition (prediction vs decidable check). They must not conflict; a conflicting row must be corrected BEFORE collection. Status is decided solely by thepass criterionagainstobserved. Ifobservedmeets the criterion but deviates fromexpected, fix the implementation to align withexpectedor mark the assertion FAIL — never rewriteexpectedto the observed value (section 8).- Fill
changed pathwith the file/function/route the assertion exercises; writen/aonly for DESIGN rows that execute no code path. At least one assertion must execute a code path changed in this diff and name it; an assertion on an untouched path does not bind. FEATURE/DATAFLOW must have at least one non-n/achanged pathcell; DESIGN may usen/a. depends on= comma-separated prerequisite ids (empty if none), collected in topological order. A prerequisite counts as satisfied only when its status isPASSorPASS-BY-USER; if it is anything else, the downstream row isNOT RUN(section 7) and anyNOT RUNmakes the gate FAIL. Thedepends ongraph must be acyclic — a cycle is FAIL. AUSER-JUDGMENTrow is a leaf: no row may list aUSER-JUDGMENTid independs on.
- Drive the real surface with commands actually available on this machine (e.g.
npm run devto start,curl -i -X POST http://localhost:3000/login -d '{"user":"a","pass":"wrong"}'for API, a real browser + DevTools for UI,tail -ffor logs). Save raw stdout/stderr/response/screenshot to numbered files (section 11).raw= the complete output as captured, not summarized, excerpted, or reordered; desensitization is a one-time transform applied at capture time, so it does not break "raw". Replace tokens / passwords / keys with***in the saved file, and record in the evidence index and beside each pasted raw blockredacted: <field name> (N occurrence(s))plus the file's sha256, so a reviewer can confirm no post-capture edit. Never desensitize status codes, error codes, or any value an assertion depends on. Any<启动命令>/<截图工具>-style placeholder left in the report = FAIL; replace it with the exact command you ran. - Reverse case FIRST. Define "one changed behavior" as each added or modified branch in the diff (an if/else, guard, validation, or new route); list every one in the report and give each a row in the assertion table. A boundary case is decidable: the same input is accepted (or behaves differently) on the pre-change implementation and rejected (or behaves correctly) after the change. Capture the pre-change baseline by reconstructing the original —
git stash, a worktree/checkout of the pre-change commit, or a saved copy of the original file — state which in the report, run the exact same command on it, and save the result as00-pre-change.log(section 11). This "show it would fail before the change" stage is the reverse-case baseline, never a terminal-FAIL assertion row (section 9). Then, for each changed behavior, run one reverse case (wrong input, missing permission, boundary value, removed precondition) and record that it fails the expected way. A bad case that also failed before the change does not count. If the case is accepted after the change, the test is not on the real path; fix and re-collect. - Dataflow: before collecting, write one line of expected transformation in
report.md(input shape -> output shape) and reference it at every hop. Then capture one real sample per hop — entry -> intermediate -> persistence -> exit — with the same correlating id. For persistence, paste the real read query and its raw return; re-printing the value you wrote is not a snapshot. Also capture the pre-change baseline for the reverse case per step 4 (00-pre-change.log): it must show the rejected value reaching exit before the change. - DESIGN observed values must come from mechanically captured sources (computed style JSON,
getBoundingClientRect, DOMtextContent, CDP output) saved as files; do not read numbers off a screenshot by eye. The baseline must give a numeric tolerance (per side <=2px, per channel <=8); exceeding it = FAIL. A screenshot is human-eye review only, never the numeric source. - Write the report from references/report-template.md; copy it, do not invent a format. Keep only the sections relevant to the selected profile(s) and delete inapplicable sections in full — deleting them does not violate "copy it, do not invent a format".
- Gate judgment (section 6): PASS only if every required item exists at the required level, every non-
USER-JUDGMENTassertion isPASS/PASS-BY-USER, at least one assertion carries a machine verdict, and there is nodepends oncycle; otherwise FAIL, UNAVAILABLE/BLOCKED, or PENDING USER (section 7).GateandResultuse the same enum and must be identical.
6. Hard gate (missing any one item = FAIL)
"Done" requires every box ticked. A missing file, missing reverse case, mock on the real path, or evidence off the diff is FAIL regardless of narrative.
- Completeness (no unknown items): the report states the assertion total N and lists a status for each of the N assertions. The only legal statuses are
PASS | FAIL | NOT RUN | UNAVAILABLE | BLOCKED | USER-JUDGMENT | PASS-BY-USER. An empty status, a status outside this set, or a listed count that differs from N is FAIL. PASS requires every non-USER-JUDGMENTrow to bePASS/PASS-BY-USERand noFAIL/NOT RUN/UNAVAILABLE/BLOCKED. USER-JUDGMENTis legal only for a dimension with NO decidable machine criterion. If a machine can judge the row, or has judged it and the condition does not hold, its status is that machine verdict (PASS/FAIL) — neverUSER-JUDGMENT. Anything a machine can measure must be its own row with a machine verdict. The assertion bound to this diff (section 3) may never beUSER-JUDGMENT. A report whose every assertion isUSER-JUDGMENThas a vacuously true PASS condition and is FAIL: at least one row must carry a machine verdict. Machine-tested and not meeting the criterion = FAIL, notUSER-JUDGMENT.depends onis a DAG: a cycle is FAIL. A prerequisite is satisfied only byPASSorPASS-BY-USER; no row may depend on aUSER-JUDGMENTrow, so such rows are leaves.- Global: binding holds (section 3), at least one assertion binds to the diff (section 5 step 2); a
USER-JUDGMENTrow never counts as PASS and never blocks another item's PASS.
| Profile | Minimum evidence set — all required |
|---|---|
| DESIGN | (a) baseline artifact with an external source: pre-existing design file + creating commit, or the user's verbatim message containing/approving it, or a spec table landed as a baseline file before any implementation file existed, with the fixed meta block (source_type, source_quote_or_path, captured_at_utc, sha256, baseline_method) filled at the moment of landing; reverse-engineering values from the implementation into the baseline is banned; (b) real render screenshot at the change commit; (c) comparison of size, color, spacing, text, state for every in-scope element (scope = every element named in the design deliverable; list excluded elements and why), each row citing baseline value and a mechanically-sourced observed value, with numeric tolerance (<=2px per side, <=8 per channel) stated in the baseline; (d) one reverse item with a value ON the tolerance boundary (e.g. 243px for a 240px spec at +/-2), shown absent/mismatching via raw output; (e) spec gaps declared explicitly: Interpretation (baseline reading written before implementation, adds position/mapping only, never contradicts a user value), Excluded (no baseline value exists, written verbatim), UNAVAILABLE (value exists but unmeasurable here) — Excluded and UNAVAILABLE in separate report sections, no silent omission; (f) >=1 evidence item on the diff. |
| FEATURE | (a) one real driven I/O transcript that executes a changed code path at the change commit; (b) one reverse case per changed behavior, its invalid input on the decidable boundary (accepted/different before the change, rejected/correct after), backed by a pre-change baseline 00-pre-change.log and raw output showing correct rejection — cases that also failed before the change do not count; (c) exact command/action and change ref recorded; (d) every assertion mapped to a file with a filled changed path, and >=1 assertion executes the changed path and names the changed file/function/route; (e) no mock/stub substituting for the chain; (f) >=1 evidence item on the diff. |
| DATAFLOW | (0) expected transformation line (input shape -> output shape) written before collection and referenced at each hop; (a) one snapshot per hop (entry, intermediate, persistence, exit) with the same correlation id; (b) persistence snapshot pastes the real read query + raw return from the store, not a re-print of the written value; (c) pre-change baseline 00-pre-change.log showing the rejected value reaches exit before the change; (d) >=1 evidence item on the diff. |
7. Non-PASS results
Grading uses the same enum as gate judgment (section 6). These are the only allowed results besides PASS.
FAIL: machine evidence insufficient: missing required item, assertion FAIL, reverse case missing, evidence off diff, mock on real surface, cycle independs on, USER-JUDGMENT on a machine-decidable row, or assertion total mismatch.FAILis the default evidence-level result.UNAVAILABLE: the evidence set is complete but one required item cannot be produced because the environment lacks the capability (no browser, no network, no device). Declare which item and why.UNAVAILABLErequires the user to supply the missing pull or to turnUNAVAILABLEintoFAIL-WAIVEDby waiver.BLOCKED: an external dependency blocks collection (service down, permission not granted, credential missing). Declare which dependency and hyperlink a manual test the user could issue once unblocked.BLOCKEDrequires the user to unblock or to turn it intoFAIL-WAIVEDby waiver.FAIL-WAIVED: a written user waiver converts aFAILintoFAIL-WAIVED. The waiver must say: "I waive the need for evidence on because ." Label the itemFAIL-WAIVEDand do not further gate it. The gate is stillFAILbecause the full evidence set is not machine-validated; only the user may accept that. Also available forUNAVAILABLEandBLOCKED.PENDING USER: a dimension for which NO machine can produce evidence (e.g. "is the button visually pleasing?"). It must be explicitly designatedUSER-JUDGMENTin the assertion table. It has no evidence file. The status staysPENDING USERuntil the user issues a judgment. Upon user approval, the status becomesPASS-BY-USER. The gate on that item is satisfied when the status isPASS-BY-USERorPASS(when the user states approval, adoption of the report, or "looks good"); the user's verbatim approval must be recorded. The item's tier must always beUSER-JUDGMENTin the evidence level column.PASS-BY-USERis neverPASS.NOT RUN: any row whosedepends onprerequisite is not satisfied. It is auto-assigned and is a terminal FAST (but not a machine-judgment row for meeting count). ANOT RUNrow in the report means the gate judgment is FAIL (no PASS). A report with aNOT RUNmust declare itself FAIL.
8. Error handling and retry
- If a command in section 5 step 3 fails (exit non-zero, no output, crash), retry once after a 5-second wait. If still failing, mark the assertion FAIL, note the error in the row, and do not re-collect. If the failure is external (service down), the result is BLOCKED, not FAIL.
- If collected evidence (file) is empty, zero-length, or unreadable, retry once. If still empty, the row is FAIL and must be labeled as such.
- If
expectedin assertion table conflicts withpass criterion(section 5 step 2), fix before collection. If evidence is collected andobservedmeetspass criterionbut deviates fromexpected, the implementation must be corrected to matchexpected, or the assertion marked FAIL. Never rewriteexpectedto matchobserved. - If the reverse case (section 5 step 4) shows the bad input was also rejected before the change, the test does not count as a valid reverse case; add a different boundary case (section 6), and if none exists, mark the assertion FAIL.
- If a machine can judge a row that was initially declared
USER-JUDGMENT, the agent must automatically convert it to a machine-judgment row, re-collect evidence if needed, and mark the statusPASS/FAIL. The machine-decidable status takes precedence over the user's initial assignment.
9. Report structure
A valid report must follow this structure. Deviations are FAIL.
# Proof Report: <task-name>
## Acceptance target (user verbatim)
> <quoted text>
## Header
- Change ref: <commit hash or sha256(file list)>
- Working tree: <free text>
- Expected registered (UTC): <time>
## Change summary
<list of files/functions/routes/components touched>
## Profile selection
<one line per selected profile and why>
## Changed behaviors (reverse case)
<list every added/modified branch; for each, the pre-change baseline file and reverse case file>
## Assertions
| id | assertion | expected | pass criterion (checkable) | changed path (file:function/route) | level required | evidence file | depends on | status |
|----|-----------|----------|---------------------------|------------------------------------|----------------|---------------|------------|--------|
| … | … | … | … | … | … | … | … | … |
## Evidence index
<list each evidence file with sha256, redaction note if any, and brief description>
## Profile-specific sections
- DESIGN: baseline reference, screenshot comparison table, spec gap declarations (Interpretation, Excluded, UNAVAILABLE)
- FEATURE: I/O transcript, reverse-case raw output per changed behavior
- DATAFLOW: expected transformation line, one snapshot per hop, persistence read query + raw return
## Gate judgment
- Gate: PASS / FAIL / UNAVAILABLE / BLOCKED / FAIL-WAIVED / PENDING USER
- Result: PASS / FAIL / UNAVAILABLE / BLOCKED / FAIL-WAIVED / PENDING USER
- Assertion totals: <N> total, <PASS count>, <FAIL count>, <NOT RUN count>, <UNAVAILABLE count>, <BLOCKED count>, <USER-JUDGMENT count>, <PASS-BY-USER count>
## Waivers (if any)
<list of FAIL-WAIVED items with user's verbatim waiver>
## User judgment requests (if any)
<list of PENDING USER items asking user approval>
10. File naming convention
All evidence files go under .proof/<task-name>/. Numbered consecutively starting at 00 for reserve-case baseline, then 01 onward for each assertion. Use short, descriptive names.
00-pre-change.log— always the pre-change baseline for the first changed behavior; can rename for clarity if multiple, e.g.00-pre-change-login.log01-positive-test.json— example for assertion 102-reverse-case.http— example for assertion 203-ui-screenshot.png— example for assertion 3
11. Main sections (abridged)
This section provides a checklist of required items per profile. It is a guide; the full requirements are in section 6.
- DESIGN: (1) external baseline artifact; (2) screenshot at change commit; (3) mechanically-sourced comparison table with tolerance; (4) one reverse case on tolerance boundary; (5) spec gap declarations; (6) >=1 evidence on diff.
- FEATURE: (1) real I/O transcript at change commit; (2) reverse case per changed behavior with pre-change baseline; (3) exact command recorded; (4) changed path on every assertion, >=1 on diff; (5) no mocks on real path; (6) >=1 evidence on diff.
- DATAFLOW: (0) expected transformation line; (1) one snapshot per hop with correlation id; (2) persistence snapshot with read query + raw return; (3) pre-change baseline showing rejection before change; (4) >=1 evidence on diff.
12. Special cases
- Screenshot-only design review: If the user asks only for a screenshot and does not request a full comparison (baseline, tolerance, reverse case), the DESIGN profile is not applicable; the agent should treat this as a simple capture request, not a proof gate. However, if the user says "prove it works" or "accept (验收)" in context of a design deliverable, then DESIGN profile is required and must include all gate items.
- Combined profiles: A single task can span DESIGN and FEATURE (e.g., implement a new UI component that also has validation logic). Both profile's minimum evidence sets must be satisfied. The report must include both profile-specific sections and the assertion table must cover items for both. The gate judgment is PASS only if both profiles pass.
- Non-runtime change: If the change has no runtime surface (e.g., pure documentation, comments, formatting, configuration-only changes, data migrations that do not alter a runtime code path), this skill yields entirely — it does not gate the task. The agent should proceed with any lighter, skill-less checks and not use this skill. However, if the user explicitly asks for verification (e.g., "prove the migration ran correctly"), then the skill may be used if the change gains a runtime surface under that request.
- Cannot do reverse case: If no valid pre-change baseline can be constructed (e.g., the change is on an uncontroversial new feature with no prior path), the agent must still attempt a reverse case by testing a different invalid input; if that fails, the row is FAIL. The skill does not allow skipping the reverse case.
13. Quick reference
- Purpose: One decision — is the work done? Hard gate, not advice.
- Core rule: Claim < Artifact (raw file) < Artifact + reverse case. Only the last two are acceptable for PASS.
- Minimum evidence per profile: DESIGN (baseline, screenshot, comparison with tolerance, reverse boundary case, spec gaps, item on diff); FEATURE (I/O transcript, reverse case per changed behavior with pre-change baseline, changed path on all assertions, no mocks, item on diff); DATAFLOW (expected transformation line, snapshots per hop, persistence read query + raw return, pre-change baseline, item on diff).
- Gate judgment: PASS only if every required item exists, all non-USER-JUDGMENT assertions PASS/PASS-BY-USER, at least one machine verdict, no cycle in depends on; else FAIL, UNAVAILABLE, BLOCKED, FAIL-WAIVED, or PENDING USER.
- Stopping conditions: (a) No acceptance target in user request — ask user and stop. (b) No matching profile — say so and stop. (c) Evidence impossible for an item — declare UNAVAILABLE/BLOCKED, never PASS. (d) Non-runtime change — yield entirely (unless user explicitly asks for verification).
- File location:
.proof/<task-name>/ - Report template: Use references/report-template.md — copy, do not invent.
- Language: Use checkable conditions in assertions; ban vague language.
- Desensitization: Replace secrets with
***at capture time; never redact status codes, error codes, or values assertions depend on; record redaction in evidence index with sha256. - Pre-change baseline: Required for every changed behavior's reverse case; use
git stash, worktree/checkout of pre-change commit, or saved copy; save as00-pre-change.log. depends on: Must form a DAG; cycle = FAIL; must not depend on a USER-JUDGMENT row.- Expected vs. observed:
expectedis before evidence; ifobservedmeets pass criterion but deviates fromexpected, fix implementation or mark FAIL — never rewriteexpectedto matchobserved. USER-JUDGMENT: Only for dimensions without decidable machine criterion; machine-decidable rows must be converted to machine verdicts; at least one row must carry a machine verdict; a USER-JUDGMENT row on the diff (section 3) is not allowed; a report with all USER-JUDGMENT rows is FAIL.- Gate and Result: Use same enum, must be identical.
14. Anti-patterns
Do NOT:
- Use this skill for writing unit tests alone, code review, proofreading text, or a proof-of-concept sketch — none of those establish that implemented work actually runs.
- Use for pure documentation, comments, formatting, configuration-only changes, or data migrations that do not change a runtime code path, unless the user explicitly asks for verification.
- Say "done", "fixed", "passing", or "shipped" while any required gate item is missing.
- Claim PASS based on reasoning, "looks right", "theoretically fine", or compilation success.
- Rely on mock, stub, or simulated data on the real path.
- Accept stale artifacts (not from working tree / change ref).
- Grant PASS to a claim-only assertion.
- Force a profile onto a change with no runtime surface.
- Omit the reverse case or declare it unnecessary.
- Rewrite
expectedto match observed value in case of conflict. - Keep a
USER-JUDGMENTon a machine-decidable row. - Leave placeholders like
<启动命令>or<截图工具>in the report. - Have a cycle in
depends on. - Produce a report with assertion count not equal to listed row count.
- Include any status outside the allowed set (
PASS | FAIL | NOT RUN | UNAVAILABLE | BLOCKED | USER-JUDGMENT | PASS-BY-USER). - Use this skill for non-runtime changes without explicit user verification request.
- Rely on human-eye review of screenshots for numeric values; those must come from mechanical sources.
- Skip profile selection and guess the evidence set.
- Write vague assertions like "the page loads correctly" without a decidable condition.
- Make a report with zero machine-decided rows.