evidence-recorder

name	evidence-recorder
description	Append one JSONL record to ~/.claude/evolution/records/ when a correction, a non-obvious win, or a repeated rework pattern occurs. Use sparingly — only when the event is load-bearing for future behavior. Do not log routine tool calls; the PreToolUse usage-logger already does that.

evidence-recorder

When to auto-use

Record an event when any of these are true:

• The user explicitly corrects an approach ("no, do X instead", "stop doing Y", "actually we prefer Z").
• A non-obvious technique produced a clear win (it worked when a naive approach would have failed).
• You notice a repeated rework pattern in the same session (doing X, being told to redo as Y, 2+ times).
• An adaptation was proposed or applied.

When NOT to use

• Routine file edits, tool calls, or test runs — those are already captured by the PreToolUse usage-logger.
• Ambiguous events. If you're not sure it's a pattern, it's noise.
• To journal your reasoning — this is an evidence store, not a diary.

How to record

Append one JSON line to the correct file:

TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
SESSION="${CLAUDE_SESSION_ID:-unknown}"   # populate from SessionStart hook if available
PROJECT=$(basename "$(pwd)")

python3 -c "
import json
rec = {
  'ts': '$TS',
  'session': '$SESSION',
  'project': '$PROJECT',
  'type': 'correction',              # one of: correction | win | friction | adaptation
  'scope': 'global',                 # global | project-specific | language:<x> | stack:<x>
  'summary': 'User corrected: prefer rsync --delete over rm before copy for setup sync.',
  'context': 'During sync of ~/.claude from repo; this prevented orphan files.',
  'id': 'evid-$TS-correction'
}
with open('$HOME/.claude/evolution/records/corrections.jsonl','a') as f:
  f.write(json.dumps(rec)+'\n')
"

Type → file mapping:

• correction → records/corrections.jsonl
• win → records/outcomes.jsonl
• friction → records/outcomes.jsonl (with success: false)
• adaptation → records/adaptations.jsonl

Schema (all fields required unless marked optional)

• ts — ISO-8601 UTC
• session — session id if available
• project — basename of CWD
• type — correction / win / friction / adaptation
• scope — global / project-specific / language: / stack:
• summary — one sentence, ≤ 200 chars
• context — optional short context, ≤ 500 chars
• id — unique identifier

Quality bar

A good record is terse, falsifiable, and future-useful. Bad example: "user was frustrated." Good example: "user prefers rsync --delete for setup sync (prevents orphan files)."