| 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}"
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.jsonlwin → records/outcomes.jsonlfriction → records/outcomes.jsonl (with success: false)adaptation → records/adaptations.jsonl
Schema (all fields required unless marked optional)
ts — ISO-8601 UTCsession — session id if availableproject — basename of CWDtype — correction / win / friction / adaptationscope — global / project-specific / language: / stack:summary — one sentence, ≤ 200 charscontext — optional short context, ≤ 500 charsid — 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)."
