/codify-learning
Transform ephemeral learnings into durable system improvements.
Philosophy
Default codify, justify exceptions. Every correction, feedback, or "I should have known" moment represents a gap in the system. Codification closes that gap.
The "3+ occurrences" threshold is a myth - we have no cross-session memory. If you learned something, codify it.
Process
- Identify Learnings
Scan the session for:
-
Errors encountered and how they were fixed
-
PR feedback received
-
Debugging insights ("the real problem was...")
-
Workflow improvements discovered
-
Patterns that should be enforced
- Brainstorm Codification Targets
For each learning, consider:
-
Hook - Should this be guaranteed/blocked? (most deterministic)
-
Lint rule - Can a lint rule catch this at edit time? → invoke /guardrail
-
Agent - Should a reviewer catch this pattern?
-
Skill - Is this a reusable workflow?
-
CLAUDE.md - Is this philosophy/convention?
Choose the target that provides the most leverage. Hooks > Lint rules > Agents > Skills > CLAUDE.md for enforcement. Skills > CLAUDE.md for workflows.
Lint rules are ideal for: import boundaries, naming conventions, deprecated API usage, auth enforcement, architectural layering violations. If the pattern can be expressed as "this code shape should never/always appear," it's a lint rule.
- Implement
For each codification:
-
Read the target file
-
Add the learning in appropriate format
-
Wire up if needed (hooks need settings.json entry)
-
Verify no duplication
- Report
CODIFIED:
- [learning] → [file]: [summary of change]
NOT CODIFIED:
- [learning]: [justification - must be specific]
Anti-Patterns
❌ "No patterns detected" - One occurrence is enough ❌ "First time seeing this" - No cross-session memory exists ❌ "Seems too minor" - Minor issues compound into major friction ❌ "Not sure where to put it" - Brainstorm, ask, don't skip ❌ "Already obvious" - If it wasn't codified, the system didn't know it
See CLAUDE.md "Continuous Learning Philosophy" for valid exceptions and the full codification philosophy.
See Also
/done — Full session retrospective (subsumes codification as one step in a broader process: went-well, friction, bugs, codify, report).