ABOUTME: Project knowledge capture through engaging LEARNING.md files
ABOUTME: Documents architecture, decisions, bugs, lessons learned in conversational style
Learning Documentation
Quality Notes
- Take your time reviewing recent work thoroughly before writing
- Quality of insights matters more than covering every change
- Re-read what you wrote: is it useful to a future reader, or just filler?
Purpose
Capture project knowledge in LEARNING.md - a living document that grows with the project. Not boring docs, but engaging technical storytelling.
When to Update
- After fixing non-trivial bugs
- After architectural decisions
- After integrating new tech
- After solving tricky problems
- Before context switches (end of day/week)
Structure
Sections: Project Overview, Architecture (mermaid diagrams), Tech Stack & Decisions (table: Technology | Why | Trade-offs), Lessons Learned (dated: Context → Problem → Solution → Takeaway), Pitfalls & Gotchas, Best Practices Discovered
Writing Style
| Do | Don't |
|---|---|
| Conversational tone | Dry technical prose |
| Analogies that clarify | Jargon without context |
| Concrete examples | Abstract descriptions |
| "We tried X, it broke because Y" | "X is not recommended" |
| Honest about mistakes | Sanitized corporate-speak |
Examples
Good:
We spent 2 hours debugging why webhooks weren't firing. Turns out Redis was silently dropping messages when memory hit 80%. Added maxmemory-policy volatile-lru and monitoring. Lesson: always monitor your message queues, silence is not golden.Bad:
Webhook reliability was improved by adjusting Redis configuration parameters.
Workflow
- Read existing LEARNING.md (or create if missing)
- Review recent work (
git log --oneline -10) - Ask what was learned, what was tricky
- Append new lessons in conversational style (dated, searchable)
- Capture solutions in
docs/solutions/[category]/for searchable reuse
Solutions Directory
For solved problems worth referencing again, create files in docs/solutions/:
docs/solutions/
├── auth/ → Authentication, authorization, sessions
├── performance/ → Profiling, caching, optimization
├── infrastructure/ → CI/CD, Docker, deployment
├── database/ → Migrations, queries, indexing
├── testing/ → Patterns, fixtures, flaky test fixes
└── debugging/ → Hard bugs, investigation techniquesFormat: docs/solutions/[category]/YYYY-MM-DD_short-description.md
Each solution file:
# Problem
[What broke / what we needed]
# Solution
[What fixed it, with code if relevant]
# Why It Works
[Root cause or design rationale, 1-3 sentences]When to use LEARNING.md vs solutions/: LEARNING.md for narrative retrospectives, architectural decisions, broad lessons. Solutions/ for specific, searchable, reusable fixes; "how did we solve X?" answers.
Vault copy: After writing to docs/solutions/, also append to vault: obsidian append file="<project> - Solutions" content="### YYYY-MM-DD: [title]\n[Problem/Solution/Why]". Creates cross-project discoverability.
Session Analysis
Analyze past sessions to identify improvement opportunities. Session files live in ~/.claude/projects/ (project paths: slashes→dashes).
CRITICAL Rules
- NEVER read raw session files (100k+ lines, token killer)
- ALWAYS use jq to extract summaries
- Focus on patterns, not individual messages
What to Look For
| Pattern | Example | Fix |
|---|---|---|
| Token waste | Read same file 5+ times | Cache key info, update CLAUDE.md |
| Wrong paths | Built feature, then found existing code | Better initial search, architecture docs |
| Repeated mistakes | Same lint error 3 sessions | Pre-commit hook, CLAUDE.md note |
| Missing automation | Manual steps every session | Script it, add to workflow |
| Context loss | Re-learn after compaction | Save state to LEARNING.md before limit |
Key jq Commands
Sessions live in ~/.claude/projects/PROJECT_NAME/session_*.json.
- Tool call counts:
jq '[.messages[].content[]? | select(.type=="tool_use") |.name] | group_by(.) | map({tool:.[0], count: length}) | sort_by(-.count)' - Repeated reads:
jq -r '... | select(.name=="Read") |.input.file_path' | sort | uniq -c | sort -rn | head -20 - Error patterns:
jq -r '... | select(.type=="tool_result" and (.content | tostring | test("error"))) |.content' | head -50
Propose Improvements As
CLAUDE.md updates, new skills, scripts, LEARNING.md entries, pre-commit hooks.
Vault Pattern Annotation
When a lesson learned maps to a skill domain, append to ## Skill Candidates in the relevant Second Brain note:
obsidian append file="Second Brain - Development" content="\n| <pattern> | <target-skill> | <project> | YYYY-MM-DD | weak |"Signal starts as weak. The knowledge-sync skill promotes to strong when 3+ projects or 2+ independent sources confirm the pattern. Create the ## Skill Candidates section (with table header) if it doesn't exist yet.