evidence-gated-review

name	evidence-gated-review
description	This skill should be used for unclear bugs, risky PR reviews, CI failures, flaky tests, security-sensitive changes, database or concurrency changes, external API changes, multi-file refactors, and investigations where claims need evidence before patching. It enforces an evidence-first Finding → Hypothesis → Review Claim → Defense → Probe → Decision → Patch → Verification → Handoff workflow so the agent does not jump to fixes, skip disconfirming checks, produce noisy review comments, or accept plausible but unverified explanations.
compatibility	Designed for Claude Code and Agent Skills-compatible coding agents with file, search, shell, test, and git access.
license	MIT

Evidence-Gated Review

Use this skill when the task needs investigation, review defense, or root-cause confidence before editing. The goal is not to make the agent slower; the goal is to prevent shallow fixes and noisy claims by turning observations into evidence-backed decisions.

This skill is selected for evidence, not speed or token economy. Do not compress away Defense, disconfirming probes, or Decision just to be brief. If the task is too small for the full ledger, use the lightweight mode below rather than silently skipping stages.

Do not use this for obvious one-step changes: typos, formatting-only edits, a single clear type error, or a tiny user-requested edit where the cause is already known.

Core model

Finding      observed fact from code, diff, logs, tests, runtime behavior
Hypothesis   possible root cause or explanation
Review Claim concrete review concern or risk candidate
Defense      check that tries to reject or qualify the claim
Probe        small verification action, including disconfirming checks
Decision     confirmed / rejected / inconclusive / deferred
Patch        smallest change tied to a confirmed claim or hypothesis
Verification targeted test, typecheck, lint, replay, or manual check
Handoff      remaining open items and next probes

Prefer evidence over consensus. Multiple reviewers agreeing can raise priority, but it is not proof. A claim becomes actionable only when source context, a failing/reproducing behavior, a specification mismatch, or a targeted probe supports it.

Depth control

Choose the lightest process that still preserves evidence:

• Lightweight inline: Use for small but non-obvious bugs or one review concern. Keep notes in the response or scratchpad. IDs are optional unless there are multiple competing items.
• Standard ledger: Use for multi-file investigations, CI failures, flaky behavior, security-sensitive findings, or anything likely to need handoff. Use concise IDs such as F-001, H-001, C-001.
• Persistent handoff: Use when work spans sessions, touches risky systems, or has several open probes. Write state files, but only the files that help the investigation.

Do not let bookkeeping become the work. If the form is taking more attention than the evidence, collapse repeated facts into one Finding, group related probes, and keep moving.

State files

For multi-step investigations that need a durable handoff, create or update only the useful subset of:

.agent-state/
  targets/
    <task-or-issue-slug>/
      findings.md
      hypotheses.md
      review-claims.md
      defenses.md
      probes.md
      session-log.md
      handoff.md

Use the templates in templates/ when creating these files. If the user does not want files written, keep the same structure in the final response. Do not create all seven files by default for a small task; findings.md, probes.md, and handoff.md are often enough.

Git handling for state files

Treat .agent-state/ as local investigation state by default:

• Do not commit .agent-state/ unless the user explicitly wants the investigation ledger preserved as a project artifact.
• Prefer adding .agent-state/ to .gitignore when state files are useful but local-only.
• Before committing, inspect status and ensure no private logs, credentials, production data, or noisy scratch files from .agent-state/ are staged.
• If handoff notes are part of the deliverable, ask whether they should live under .agent-state/, project docs, an issue/PR comment, or the final response.

Guardrails

• Do not patch before the defense/probe pass when root cause is unclear.
• Stop and ask before destructive actions, production-like endpoints, credentials, payment flows, external side effects, or broad rewrites.
• Default investigation budget unless the user says otherwise. These are starting limits, not magic constants; lower them for narrow tasks, raise them for high-risk work only after saying why.
  • max investigation iterations: 5
  • max planned probes at once: 5
  • max test retries for the same command: 1
  • max new state/template files per target: 8
• If two probes for the same hypothesis are inconclusive, stop and hand off instead of looping unless the user explicitly approves another probe and the new probe is meaningfully different.
• Always include at least one disconfirming probe for plausible hypotheses or risky review claims.

Workflow

1. Finding

Read the request, relevant diffs, failing logs, tests, and nearby code. Record facts only as Findings. Avoid conclusions in Findings.

Good Finding:

F-003: `POST /reservations` accepts `deposit` from the client payload in `src/api/reservations.ts`.
Evidence: line X reads `deposit` from `body` and passes it to `createReservation`.

Bad Finding:

Validation is broken.

2. Hypothesis

Use Hypotheses for possible explanations of observed behavior: why a test fails, why a regression appears, why a race occurs, or why a system behaves differently than expected. A hypothesis should connect specific Findings to a possible cause and name what would make it false.

3. Review Claim

Use Review Claims for concrete concerns that may deserve action: PR comments, security risks, API contract mismatches, data-loss risks, concurrency hazards, or design review issues. A claim must include affected file/symbol, concrete risk, evidence, possible false-positive reason, and suggested probe.

In mixed sessions, keep the distinction by intent:

• If it explains an observed failure, write a Hypothesis.
• If it asserts an actionable risk or defect, write a Review Claim.
• If a bug investigation uncovers an unrelated possible issue, keep it as a Finding or open question until you can state the concrete risk and probe it. Do not duplicate the same idea as both H-* and C-* unless one explains cause and the other states a separate review risk.

4. Defense

For each plausible hypothesis or review claim, attempt to reject it before accepting it. Check source context, existing tests, runtime paths, API contracts, and counter-evidence. Mark weak, style-only, or unsupported claims as rejected.

5. Probe

Create small verification actions. Prefer targeted tests, minimal reproductions, grep/code search, typecheck, lint, logs, or browser interactions over broad rewrites.

Each important hypothesis or risky review claim should have:

Supporting probe: result expected if the hypothesis/claim is true
Disconfirming probe: result expected if the hypothesis/claim is false or scoped differently
Scope probe: optional check for whether this is local or systemic

6. Decision

After defense and probes, name the decision before editing:

confirmed: evidence supports action now
rejected: counter-evidence or source context defeats it
inconclusive: evidence is insufficient; hand off or ask for scope
deferred: real concern but outside current request or budget

If no claim or hypothesis survives defense, say so clearly and do not invent a patch.

7. Patch

Patch only confirmed claims/hypotheses. Make the smallest change that addresses the confirmed cause. Do not refactor adjacent code unless the confirmed fix requires it.

8. Verification

Run targeted verification first. Then run broader checks only when justified by the risk and project conventions. Record command, result, and conclusion.

9. Handoff

Summarize:

• confirmed and fixed items
• rejected claims and why
• inconclusive probes
• remaining open hypotheses
• next 1–3 recommended probes

Output expectations

When reporting to the user, prefer this structure:

Findings
- F-001 ...

Claims / Hypotheses
- C-001 / H-001 ... status: confirmed|rejected|inconclusive

Defense and probes
- What was checked, what would have disproved it, and result

Patch
- Minimal files changed and why

Verification
- Commands/checks run and results

Handoff
- Remaining risks and next probes

If no claim or hypothesis survives defense, say so clearly and do not invent a patch.