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.

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:

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