By name: expectations description: Capture learnings, gotchas, and architectural decisions into the right project documentation while context is fresh. Use when capturing learnings, documenting gotchas, recording architectural decisions, or deciding where a piece of knowledge should live. Triggers on "document this", "remember this pattern", "what should I know about", or after completing significant features.
Expectations: Capturing Learnings
Core philosophy (TDD, refactoring discipline, commit approval) lives in CLAUDE.md and is always loaded — this skill covers what CLAUDE.md does not: deciding what to document, where it goes, and in what format.
One workflow rule bears repeating because it gates documentation work too: never commit without explicit user approval. After refactoring, verify all tests and static analysis pass, then STOP and wait for commit approval.
Documentation Framework
At the end of every significant change, ask: "What do I wish I'd known at the start?"
Document if ANY of these are true:
- Would save future developers significant time
- Prevents a class of bugs or errors
- Reveals non-obvious behavior or constraints
- Captures architectural rationale or trade-offs
- Documents domain-specific knowledge
- Identifies effective patterns or anti-patterns
- Clarifies tool setup or configuration gotchas
Do NOT document what the repo already records: code structure, git history, anything derivable by reading the code.
Types of Learnings to Capture
- Gotchas: Unexpected behavior discovered (e.g., "API returns null instead of empty array")
- Patterns: Approaches that worked particularly well
- Anti-patterns: Approaches that seemed good but caused problems
- Decisions: Architectural choices with rationale and trade-offs
- Edge cases: Non-obvious scenarios that required special handling
- Tool knowledge: Setup, configuration, or usage insights
Where Each Learning Goes
| Learning | Destination | Why |
|---|---|---|
| Gotcha, pattern, anti-pattern, tool knowledge that affects how Claude works in this repo | Project CLAUDE.md |
Loaded every session for this project |
| Architectural decision with rationale and rejected alternatives | ADR (docs/adr/ or project convention) — use the adr agent |
Decisions need permanence and context beyond a config file |
| In-flight discoveries during planned work (blockers, scope changes) | The active plan file in plans/ |
Travels with the work; merged or discarded when the plan completes |
| Cross-project user preferences and corrections | Auto-memory (MEMORY.md) |
Persists across projects and sessions |
| User-facing behavior, setup steps, API usage | README / docs — use the docs-guardian agent |
Humans read these, not CLAUDE.md |
When several learnings accumulate at the end of a feature, launch the learn agent to sweep the session for documentation-worthy insights rather than relying on recall.
Documentation Format
#### Gotcha: [Descriptive Title]
**Context**: When this occurs
**Issue**: What goes wrong
**Solution**: How to handle it
// CORRECT - Solution
const example = "correct approach";
// WRONG - What causes the problem
const wrong = "incorrect approach";
Keep entries scannable: a future reader should grasp context, issue, and solution in under ten seconds.
Communication
- Be explicit about trade-offs in different approaches
- Explain the reasoning behind significant design decisions
- Flag any deviations from guidelines with justification
- Suggest improvements that align with these principles
- When unsure, ask for clarification rather than assuming