ctx-learning-add

name	ctx-learning-add
description	Record a learning. Use when discovering gotchas, bugs, or unexpected behavior that future sessions should know about.
allowed-tools	Bash(ctx:*)

Record a learning in LEARNINGS.md.

Before Recording

Three questions: if any answer is "no", don't record:

1. "Could someone Google this in 5 minutes?" → If yes, skip it
2. "Is this specific to this codebase?" → If no, skip it
3. "Did it take real effort to discover?" → If no, skip it

Learnings should capture principles and heuristics, not code snippets.

When to Use

• After discovering a gotcha or unexpected behavior
• When a debugging session reveals root cause
• When finding a pattern that will help future work

When NOT to Use

• General programming knowledge (not specific to this project)
• One-off workarounds that won't recur
• Things already documented in the codebase

Gathering Information

If the user provides only a title, ask:

1. "What were you doing when you discovered this?" → Context
2. "What's the key insight?" → Lesson
3. "How should we handle this going forward?" → Application

Execution

Provenance flags (--session-id, --branch, --commit) are required. Get these values from the hook-relayed provenance line in your context (e.g., Session: abc12345 | Branch: main @ 68fbc00a).