Evidence Review
The reader of this review is a maintainer who will act on every line of it.
A false or misaligned finding costs them more than a missed nit: they chase it,
lose trust, and start skimming. So optimize for signal. Report only what you
have shown to be true, and say plainly when nothing survived. No findings is
better than bad findings.
The bar is not "tests pass". It is: would this repo's maintainer stand behind
the change as is?
Inputs
- Spec: use the one you are given, or a PR description already in hand.
Don't go looking for one. With no spec, review for BUG and CONVENTION only,
since MISSING and UNNECESSARY are judged against the spec.
- Change: the given diff, branch, PR, or commit range; otherwise the
current branch against its merge-base with main, plus uncommitted changes.
- House rules:
REVIEW.md, CONTRIBUTING.md, CLAUDE.md, AGENTS.md, or
similar maintainer-written files, if present.
Do not edit source files. You may write tests to prove a finding; list each one
you wrote in the report so the maintainer can keep or delete it.
The four kinds of finding
- BUG: wrong behavior for an input or state that can actually occur,
including side effects on callers, stored data, or external systems.
- MISSING: something the spec requires that is absent, stubbed, or only
partly wired up (for example, implemented but unreachable from the entry
point the spec names).
- UNNECESSARY: code, options, abstractions, or dependencies the spec did
not ask for and nothing in the change needs.
- CONVENTION: a break from a written house rule, or from the way this
repo already solves the same problem.
Everything else is out of scope: style, naming, formatting, and comments
that no written house rule covers, "consider" or "might" suggestions, hypothetical future needs, and anything a
linter or type checker already enforces. Problems the change did not introduce
are out of scope too, unless the change makes them reachable or worse.
What counts as evidence
Each finding needs evidence the maintainer can check in a minute. Your
confidence is not evidence, and neither is code that merely looks wrong.
- BUG: a test or command you ran, with the exact command, the actual
result, and the expected one. When running is truly impossible (needs
production, real hardware, or a timing window you cannot force), give a
step-by-step trace from a concrete input through file:line to the wrong
result, and mark the finding traced, not run. A trace with a gap is not
evidence.
- MISSING: the spec line quoted, plus what you ran or read that shows the
gap.
- UNNECESSARY: the location, plus a search showing nothing in the change or
spec uses it. "No test fails without it" is weak on its own, because the code
may simply be untested.
- CONVENTION: the house rule quoted, or two existing places in the repo
that do it the established way. Your preference is not a convention.
How to work
- Map the change. Read the diff, then the callers and callees of every
changed function. Many real bugs live where the new code meets the old.
- List the checks. Write down each spec requirement and each house rule
that applies. This is the checklist MISSING and CONVENTION come from.
- Exercise, don't read. Verify each suspected bug and each requirement by
running it: a focused test, a script, or the CLI. "The code looks like it
handles this" does not verify it.
- Probe the edges of changed code with the inputs that apply: empty,
boundary, invalid, repeated, concurrent, partial failure, and existing data
written by the old version.
- Attack your own findings. For each one, look for the reason it is wrong:
a guard upstream, a caller that never passes that input, a spec line that
allows it, a deliberate design or security choice. Drop what does not
survive, and anything that would not block the change. Most first-draft
findings should not survive.
- If already merged, drop anything a later commit fixed.
- Be honest about coverage. If you could not verify some part (too large,
no way to run it, missing credentials), name it under Not verified. Never
imply you checked what you did not.
Output
Use this shape and nothing else. No summary of the change, no praise, no
general remarks: the maintainer already knows what the change is.
Verdict: PASS | PASS (partial) | FIX
High-risk: <paths touched, or "none">
[BUG | MISSING | UNNECESSARY | CONVENTION] one-line statement
Where: file:line (for MISSING, the entry point the spec names)
Evidence: command and output, test name, spec line, or rule
Impact: what breaks, for whom (a concrete caller or scenario, not "could")
Not verified: <parts you could not check, or omit>
Tests written: <paths, or omit>
- Name code by its exact identifier from the source, never a paraphrase.
- PASS means nothing survived and nothing important went unchecked. That
is a good result; do not pad it with minor findings to look thorough.
- PASS (partial) means nothing survived, but a spec requirement or
high-risk path is under Not verified.
- FIX means at least one finding follows.
- High-risk lists touched paths in auth, payments, migrations, public
APIs, infra, secrets, and similar. Review these yourself, whatever the
verdict.
Order findings by impact: data loss, security, and wrong results first, then
unmet requirements, then convention breaks, then unnecessary code. Report at
most seven, since a longer list buries the ones that matter. If more survived,
add one line saying how many lower-impact findings you left out.
1---2name: evidence-review3description: >-4 Review a code change against its spec and the repo's own conventions, and5 report only findings you have proven: reproduced bugs, unmet requirements,6 code nothing needs, and broken house rules, ending in a PASS or FIX verdict.7disable-model-invocation: true8metadata:9 source: https://skillmd.com/skills/itsmostafa/evidence-review10---1112# Evidence Review1314The reader of this review is a maintainer who will act on every line of it.15A false or misaligned finding costs them more than a missed nit: they chase it,16lose trust, and start skimming. So optimize for signal. Report only what you17have shown to be true, and say plainly when nothing survived. No findings is18better than bad findings.1920The bar is not "tests pass". It is: would this repo's maintainer stand behind21the change as is?2223## Inputs2425- **Spec:** use the one you are given, or a PR description already in hand.26 Don't go looking for one. With no spec, review for BUG and CONVENTION only,27 since MISSING and UNNECESSARY are judged against the spec.28- **Change:** the given diff, branch, PR, or commit range; otherwise the29 current branch against its merge-base with main, plus uncommitted changes.30- **House rules:** `REVIEW.md`, `CONTRIBUTING.md`, `CLAUDE.md`, `AGENTS.md`, or31 similar maintainer-written files, if present.3233Do not edit source files. You may write tests to prove a finding; list each one34you wrote in the report so the maintainer can keep or delete it.3536## The four kinds of finding37381. **BUG:** wrong behavior for an input or state that can actually occur,39 including side effects on callers, stored data, or external systems.402. **MISSING:** something the spec requires that is absent, stubbed, or only41 partly wired up (for example, implemented but unreachable from the entry42 point the spec names).433. **UNNECESSARY:** code, options, abstractions, or dependencies the spec did44 not ask for and nothing in the change needs.454. **CONVENTION:** a break from a written house rule, or from the way this46 repo already solves the same problem.4748Everything else is out of scope: style, naming, formatting, and comments49that no written house rule covers, "consider" or "might" suggestions, hypothetical future needs, and anything a50linter or type checker already enforces. Problems the change did not introduce51are out of scope too, unless the change makes them reachable or worse.5253## What counts as evidence5455Each finding needs evidence the maintainer can check in a minute. Your56confidence is not evidence, and neither is code that merely looks wrong.5758- **BUG:** a test or command you ran, with the exact command, the actual59 result, and the expected one. When running is truly impossible (needs60 production, real hardware, or a timing window you cannot force), give a61 step-by-step trace from a concrete input through file:line to the wrong62 result, and mark the finding **traced, not run**. A trace with a gap is not63 evidence.64- **MISSING:** the spec line quoted, plus what you ran or read that shows the65 gap.66- **UNNECESSARY:** the location, plus a search showing nothing in the change or67 spec uses it. "No test fails without it" is weak on its own, because the code68 may simply be untested.69- **CONVENTION:** the house rule quoted, or two existing places in the repo70 that do it the established way. Your preference is not a convention.7172## How to work73741. **Map the change.** Read the diff, then the callers and callees of every75 changed function. Many real bugs live where the new code meets the old.762. **List the checks.** Write down each spec requirement and each house rule77 that applies. This is the checklist MISSING and CONVENTION come from.783. **Exercise, don't read.** Verify each suspected bug and each requirement by79 running it: a focused test, a script, or the CLI. "The code looks like it80 handles this" does not verify it.814. **Probe the edges** of changed code with the inputs that apply: empty,82 boundary, invalid, repeated, concurrent, partial failure, and existing data83 written by the old version.845. **Attack your own findings.** For each one, look for the reason it is wrong:85 a guard upstream, a caller that never passes that input, a spec line that86 allows it, a deliberate design or security choice. Drop what does not87 survive, and anything that would not block the change. Most first-draft88 findings should not survive.896. **If already merged,** drop anything a later commit fixed.907. **Be honest about coverage.** If you could not verify some part (too large,91 no way to run it, missing credentials), name it under *Not verified*. Never92 imply you checked what you did not.9394## Output9596Use this shape and nothing else. No summary of the change, no praise, no97general remarks: the maintainer already knows what the change is.9899```text100Verdict: PASS | PASS (partial) | FIX101High-risk: <paths touched, or "none">102103[BUG | MISSING | UNNECESSARY | CONVENTION] one-line statement104Where: file:line (for MISSING, the entry point the spec names)105Evidence: command and output, test name, spec line, or rule106Impact: what breaks, for whom (a concrete caller or scenario, not "could")107108Not verified: <parts you could not check, or omit>109Tests written: <paths, or omit>110```111112- Name code by its exact identifier from the source, never a paraphrase.113- **PASS** means nothing survived and nothing important went unchecked. That114 is a good result; do not pad it with minor findings to look thorough.115- **PASS (partial)** means nothing survived, but a spec requirement or116 high-risk path is under *Not verified*.117- **FIX** means at least one finding follows.118- **High-risk** lists touched paths in auth, payments, migrations, public119 APIs, infra, secrets, and similar. Review these yourself, whatever the120 verdict.121122Order findings by impact: data loss, security, and wrong results first, then123unmet requirements, then convention breaks, then unnecessary code. Report at124most seven, since a longer list buries the ones that matter. If more survived,125add one line saying how many lower-impact findings you left out.