git:20260519.d26d419 to git:20260909.6778255

13 added, 61 removed. Audit A to A.

---

name: evidence-based-development

description: "Enforce evidence-based claims through file:line citations, P1/P2/P3 prioritization proportional to evidence, and the ASSERTION/EVIDENCE/VERIFIED pattern for behavioral claims before any recommendation. Use when gathering evidence, presenting findings, or making development decisions. This skill MUST be consulted because confidence is not evidence, and ungrounded claims cause incorrect development decisions."

allowed-tools: Bash, Read, Grep, Glob

---

# Evidence-Based Development

- Foundation skill that governs how Claude gathers, presents, and acts on evidence during development.

## Iron Law

**EVIDENCE BEFORE CLAIMS, ALWAYS. If you haven't read the code, you don't know what it does.**

- This is non-negotiable. No recommendation without a citation. No behavioral claim without verification. Confidence is not evidence.

+ No recommendation without a citation. No behavioral claim without verification. Confidence is not evidence.

## Show Before Decide

- Never propose a change without first showing the current state. Read the file, cite the line, then suggest.

- **Pattern**: "Here's what I found at `file.rb:42` → here's what I recommend → here's why."

+ Never propose a change without first showing the current state: "Here's what I found at `file.rb:42` → here's what I recommend → here's why."

## Citation Requirements

- Every claim about code must include a file:line reference. No exceptions.

- - Use `file_path:line_number` format in all findings

- - When reviewing diffs, cite both the file and the specific hunk

- - When reporting issues, show the exact code snippet as evidence

+ Every claim about code carries a `file_path:line_number` reference. When reviewing diffs, cite the file and the specific hunk. When reporting issues, show the exact code snippet.

## Finding Prioritization

- All findings, review comments, and issues use P1/P2/P3 classification. This priority system operationalizes the organizational hard boundary **"No Ungrounded Claims"** — every finding must carry evidence (file:line citation, test output, runtime observation) proportional to its priority, and no recommendation may be made without verification against current sources.

+ All findings, review comments, and issues use P1/P2/P3. This operationalizes the organizational hard boundary **"No Ungrounded Claims"**: every finding carries evidence (file:line, test output, runtime observation) proportional to its priority.

| Priority | Meaning | Action |

|----------|---------|--------|

| **P1** | Must fix — blocks merge, security issue, data loss risk, broken functionality | Fix before proceeding |

| **P2** | Should fix — logic error, missing edge case, test gap, convention violation | Fix in this PR |

| **P3** | Consider — style preference, optimization opportunity | Fix in-PR by default. Cosmetic P3 in untouched files: fix-if-bounded or document inline (default) / follow-up issue (`minimalScope` mode only). Finding triage is NEVER a valid escalation trigger — see `skills/llm-operator-principles/SKILL.md`. |

## ASSERTION/EVIDENCE/VERIFIED Pattern

- For any non-trivial claim about code behavior:

- 1. **ASSERTION**: State what you believe to be true

- 2. **EVIDENCE**: Show the code/output/test that supports it

- 3. **VERIFIED**: Confirm by running a test, reading the actual code, or checking behavior

+ For any non-trivial claim about code behavior (behavioral claims, security assessments, performance analysis — not obvious facts):

- Skip this pattern for obvious facts (e.g., "this file exists"). Use it for behavioral claims, security assessments, and performance analysis.

+ 1. **ASSERTION**: what you believe to be true

+ 2. **EVIDENCE**: the code/output/test that supports it

+ 3. **VERIFIED**: confirmed by running a test, reading the actual code, or checking behavior

## Finding-First Display

- Always display findings BEFORE recommendations or actions:

- 1. Show the finding table (sorted P1 → P2 → P3)

- 2. Show affected files with citations

- 3. Then propose actions

- 4. Then ask for decisions (if needed)

- Never bury findings after a long narrative. The human should see issues immediately.

+ Show findings BEFORE recommendations or actions: the finding table (sorted P1 → P2 → P3), then affected files with citations, then proposed actions, then decisions (if needed). Never bury findings after narrative.

## Deduplication

- When synthesizing findings from multiple sources (agents, reviews, tools):

- - Deduplicate by `file:line` — same location means same finding

- - Keep the highest priority version

- - Merge descriptions if they add different context

- - Note the source of each finding for traceability

+ When synthesizing findings from multiple sources (agents, reviews, tools): deduplicate by `file:line`; keep the highest priority; merge descriptions that add context; note each finding's source.

## Verification Methods

- Every skill should include a verification step. Common patterns:

- | Method | When to Use |

- |--------|-------------|

- | Run tests | After code changes |

- | Read code / check git diff | Before behavioral claims or after edits |

- | Parallel Bash | Run independent checks simultaneously |

- | Agent(Explore) | Investigate unfamiliar code in separate context |

+ Run tests after code changes. Read code or `git diff` before behavioral claims and after edits. Run independent checks as parallel Bash calls. Use Agent(Explore) for unfamiliar code in a separate context.

## Stop Conditions

- Stop and reassess when:

- - You've made 2+ claims without file:line citations in this session

- - You're about to recommend a change to a file you haven't read

- - Evidence contradicts your initial assumption — update the assumption, don't explain away the evidence

- - You find yourself writing "should" or "probably" about code behavior — go verify

+ Stop and reassess when: you've made 2+ claims without file:line citations; you're about to recommend a change to a file you haven't read; evidence contradicts your assumption (update the assumption, don't explain away the evidence); you're writing "should" or "probably" about code behavior — go verify.

## Graceful Degradation

- When evidence is unavailable:

- - State what you couldn't verify and why

- - Proceed with reduced confidence, flagging assumptions

- - Never fabricate evidence or cite files you haven't read

- ## Rationalization Prevention

- | Excuse | Response |

- |--------|----------|

- | "I'm pretty sure this is how it works" | Pretty sure is not evidence. Read the file. |

- | "I already checked earlier" | Earlier is stale. Show fresh evidence. |

- | "This is obvious from the pattern" | Obvious claims need obvious proof. Cite file:line. |

- | "Checking would take too long" | Unchecked claims waste more time when wrong. |

- | "The user already knows this" | The citation is for accuracy, not the audience. |

+ When evidence is unavailable: state what you couldn't verify and why; proceed with reduced confidence, flagging assumptions; never fabricate evidence or cite files you haven't read. "I already checked earlier" is stale — show fresh evidence.