evidence-based-development

What this skill does

# 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.

## 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."

## 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

## 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.

| 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

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

## 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.

## 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

## 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 |

## 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

## 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. |