PR proof
rules/pr-evidence-report.md states the contract. This skill produces the artifact.
Codex loads AGENTS.md and does not expand Markdown @ imports, so this file is
read directly rather than pulled in by reference. Every path below is explicit
for the same reason.
A diff shows what changed. It cannot show what a person can now do that they
could not before, and it cannot show that anyone watched it happen. Gates prove
the code compiles and the assertions pass; a green gate has never demonstrated a
feature. The report is where that evidence goes.
Before you build anything
Ask whether the report is earned. It is earned by having evidence to show —
never by policy. Write Markdown and stop unless the change needs at least one of:
- Screenshots whose captions must stay attached to them.
- Collapsible sections, because there is superseded evidence or long output.
- Copy buttons, because a reader will execute the manual steps.
- Before/after side by side at equal height.
A refactor with no user-visible change needs none of those.
Gather first, write second
Do not open the template until you can fill these. Each one you cannot fill is
either a gap to close or a line for the limits section.
| Slot |
How to get it |
| The claim |
One sentence naming the end-to-end thing a person can now do. If it cannot be stated as a complete job someone finishes through the real flow, it is not a claim yet. |
| Before SHA |
git merge-base origin/<trunk> HEAD |
| After SHA |
git rev-parse HEAD |
| Screenshots |
Drive the real running product. Capture the window, not a mock, a fixture harness or a dev-server page. |
| Provenance per shot |
Process id, window id, timestamp, which binary, which profile or tenant. A screenshot without it is decoration. |
| Manual steps |
Every command verified to exist this session. Never forward a command from a stale runbook. |
| Pass criterion |
Per step, observable. "Looks right" is not one. |
| Traps |
Failure modes that look like your change and are not. Each with its tell. |
| Limits |
What you did not check. Always non-empty in practice. |
A capture you could not take is a capture-gap, not silence. The template
has a bordered placeholder. Omitting a shot reads as "nothing to see"; the gap
reads as "not established", which is the truth.
Build it
- Copy
assets/report-template.html to
docs/reports/YYYY-MM-DD-<slug>.html — or docs/checklists/ for a
hand-check, docs/runbooks/ for a procedure. Follow the repo's existing
docs/ layout; do not invent a folder.
- Put images in
docs/<kind>/assets/<slug>/ beside it. Commit them.
- Fill the seven sections in order. The order is the argument: claim →
evidence → limits, never the reverse.
- Headings are claims, not labels. "Stop is where the words are" beats
"Streaming behaviour". A heading that could sit above any section of any
report is a wasted line — the reader skims headings, so put the finding there.
- Link it from the PR body.
The seven sections
| # |
Section |
Holds |
| 1 |
The claim |
One falsifiable sentence. Not "improves X" — that asserts nothing. |
| 2 |
Before / after |
Behaviour first, code only where the code is the point. Each panel labelled with its SHA. |
| 3 |
What a person actually sees |
Screenshots, each captioned with provenance. |
| 4 |
Prove it yourself |
Numbered steps, every command in a copy block, every step ending in Pass:. |
| 5 |
Traps |
The failure modes that mimic your change. |
| 6 |
What this proves that the tests cannot |
If you cannot fill this, you did not need a report. |
| 7 |
What I have NOT checked |
Always present. Always last. Never softened. |
Three rules that decide whether the report is honest
Never collapse the claim, the limits, or a failure. <details> holds
secondary and superseded evidence — a capture a later one replaced, long raw
output, a remaining-checks list. A reader who expands nothing must still come
away with the correct impression, including the bad parts. Collapsing a caveat is
how a report lies without containing a false sentence.
data-copy and the <pre> must stay byte-identical. They drift the moment
someone edits one, and the copied command then differs from the reviewed one.
One command per block — a reader pastes blocks, they do not parse them.
"Before" without a SHA is unverifiable. The past is where a
plausible-and-wrong story is cheapest to tell, so anchor both panels.
Checks before you link it
Where it does not go
Not a hosted page, not a gist, not a chat attachment. A report outside the repo
is reviewed by nobody, found by no future reader, moves with nothing, and leaves
no history when deleted. See rules/documents-not-artifacts.md.
1---2name: pr-proof3description: "Build the HTML evidence report a PR ships — the claim, before/after anchored to commit SHAs, screenshots with provenance, copy-paste manual test steps, and what was NOT checked. Use when a PR changes a user-visible surface, when a reviewer asks to be shown, or when someone says prove it, proof, evidence report, PR report, before and after, or hand-check. Produces one self-contained file under docs/, committed in the branch and linked from the PR body."4metadata:5 source: https://skillmd.com/skills/decebal/pr-proof6---78# PR proof910`rules/pr-evidence-report.md` states the contract. This skill produces the artifact.1112Codex loads `AGENTS.md` and does not expand Markdown `@` imports, so this file is13read directly rather than pulled in by reference. Every path below is explicit14for the same reason.1516A diff shows what changed. It cannot show **what a person can now do that they17could not before**, and it cannot show that anyone watched it happen. Gates prove18the code compiles and the assertions pass; a green gate has never demonstrated a19feature. The report is where that evidence goes.2021## Before you build anything2223**Ask whether the report is earned.** It is earned by having evidence to show —24never by policy. Write Markdown and stop unless the change needs at least one of:25261. Screenshots whose captions must stay attached to them.272. Collapsible sections, because there is superseded evidence or long output.283. Copy buttons, because a reader will *execute* the manual steps.294. Before/after side by side at equal height.3031A refactor with no user-visible change needs none of those.3233## Gather first, write second3435Do not open the template until you can fill these. Each one you cannot fill is36either a gap to close or a line for the limits section.3738| Slot | How to get it |39|---|---|40| **The claim** | One sentence naming the end-to-end thing a person can now do. If it cannot be stated as a complete job someone finishes through the real flow, it is not a claim yet. |41| **Before SHA** | `git merge-base origin/<trunk> HEAD` |42| **After SHA** | `git rev-parse HEAD` |43| **Screenshots** | Drive the real running product. Capture the window, not a mock, a fixture harness or a dev-server page. |44| **Provenance per shot** | Process id, window id, timestamp, which binary, which profile or tenant. A screenshot without it is decoration. |45| **Manual steps** | Every command verified to exist **this session**. Never forward a command from a stale runbook. |46| **Pass criterion** | Per step, observable. "Looks right" is not one. |47| **Traps** | Failure modes that look like your change and are not. Each with its tell. |48| **Limits** | What you did not check. Always non-empty in practice. |4950**A capture you could not take is a `capture-gap`, not silence.** The template51has a bordered placeholder. Omitting a shot reads as "nothing to see"; the gap52reads as "not established", which is the truth.5354## Build it55561. Copy `assets/report-template.html` to57 `docs/reports/YYYY-MM-DD-<slug>.html` — or `docs/checklists/` for a58 hand-check, `docs/runbooks/` for a procedure. Follow the repo's existing59 `docs/` layout; do not invent a folder.602. Put images in `docs/<kind>/assets/<slug>/` beside it. Commit them.613. Fill the seven sections **in order**. The order is the argument: claim →62 evidence → limits, never the reverse.634. Headings are **claims, not labels**. "Stop is where the words are" beats64 "Streaming behaviour". A heading that could sit above any section of any65 report is a wasted line — the reader skims headings, so put the finding there.665. Link it from the PR body.6768## The seven sections6970| # | Section | Holds |71|---|---|---|72| 1 | The claim | One falsifiable sentence. Not "improves X" — that asserts nothing. |73| 2 | Before / after | Behaviour first, code only where the code *is* the point. Each panel labelled with its SHA. |74| 3 | What a person actually sees | Screenshots, each captioned with provenance. |75| 4 | Prove it yourself | Numbered steps, every command in a copy block, every step ending in **Pass:**. |76| 5 | Traps | The failure modes that mimic your change. |77| 6 | What this proves that the tests cannot | If you cannot fill this, you did not need a report. |78| 7 | What I have NOT checked | Always present. Always last. Never softened. |7980## Three rules that decide whether the report is honest8182**Never collapse the claim, the limits, or a failure.** `<details>` holds83secondary and superseded evidence — a capture a later one replaced, long raw84output, a remaining-checks list. A reader who expands nothing must still come85away with the correct impression, including the bad parts. Collapsing a caveat is86how a report lies without containing a false sentence.8788**`data-copy` and the `<pre>` must stay byte-identical.** They drift the moment89someone edits one, and the copied command then differs from the reviewed one.90One command per block — a reader pastes blocks, they do not parse them.9192**"Before" without a SHA is unverifiable.** The past is where a93plausible-and-wrong story is cheapest to tell, so anchor both panels.9495## Checks before you link it9697- [ ] Opens from `file://` with no network — inline `<style>`, inline `<script>`, no CDN98- [ ] Every `data-copy` matches its `<pre>` exactly99- [ ] Every command was verified to exist this session100- [ ] Every screenshot caption carries provenance101- [ ] Section 7 is present, last, and not empty102- [ ] Nothing load-bearing is inside `<details>`103- [ ] Renders at phone width; `prefers-reduced-motion` respected104- [ ] Committed in the branch, not pasted into a comment or hosted elsewhere105106## Where it does not go107108Not a hosted page, not a gist, not a chat attachment. A report outside the repo109is reviewed by nobody, found by no future reader, moves with nothing, and leaves110no history when deleted. See `rules/documents-not-artifacts.md`.