By name: learnings description: Manage project learnings — read and write gotchas, patterns, decisions, and discoveries to docs/learnings/
Learnings Skill
This skill manages project learnings — insights, gotchas, patterns, and decisions discovered during development.
Directory Structure
Learnings are stored in docs/learnings/ at the project root:
docs/learnings/
├── gotchas.md # Traps, pitfalls, things that bite you
├── patterns.md # "This is how we do X here"
├── decisions.md # Architectural/technical decisions and rationale
└── discoveries.md # TIL moments, how things work in this codebase
Categories
When categorizing a learning, use this guide:
| Category | Use When | Examples |
|---|---|---|
| Gotchas | Something unexpected that caused issues or could cause issues | Silent failures, implicit behavior, edge cases, misleading names |
| Patterns | A repeated way of doing things in this codebase | "Always use X for Y", naming conventions, preferred libraries |
| Decisions | A choice was made with explicit reasoning | "We use X instead of Y because Z", trade-offs, constraints |
| Discoveries | You learned how something works | Internal APIs, undocumented behavior, codebase structure |
If a learning fits multiple categories, pick the primary one. Don't duplicate.
Entry Format
Each learning is appended to the top of the relevant file (newest first):
## Short descriptive title
**Ticket:** ABC-123
**Date:** 2025-01-25
The actual learning content goes here. Be concise but complete.
Include file paths with line numbers when relevant (e.g., `src/auth/token.ts:42`).
---
Reading Learnings
When starting work (research, planning, implementation):
- Check if
docs/learnings/exists - If it does, scan all files for learnings relevant to the current task
- Consider these learnings when making decisions
Relevance signals:
- Same area of the codebase
- Similar problem domain
- Related tickets mentioned
- Keywords matching the current task
Writing Learnings
At the end of implementation or on-demand:
- Reflect on the work done in the current session
- Identify insights that would help future work:
- What was surprising?
- What took longer than expected?
- What would you want to know if you came back to this code?
- What patterns did you follow or establish?
- Categorize each learning
- Create the
docs/learnings/directory if it doesn't exist - Append each learning to the appropriate file using the entry format
Auto-Extraction Guidelines
When auto-extracting learnings from a session, look for:
- Error messages that required investigation
- Code that needed refactoring to work
- Implicit dependencies or requirements
- Workarounds for framework/library limitations
- Established patterns used or created
- Decisions made with trade-offs
- Non-obvious file relationships
- API quirks or undocumented behavior
Skip trivial learnings like:
- Standard library usage
- Common framework patterns
- Things already documented in the codebase
- One-off typos or mistakes
File Initialization
If a learnings file doesn't exist, create it with this header:
# Gotchas
Things that might bite you. Check here before you get bitten.
---
(Adjust the title and description for each category)
Headers for Each File
gotchas.md:
# Gotchas
Things that might bite you. Check here before you get bitten.
---
patterns.md:
# Patterns
How we do things around here. Follow these for consistency.
---
decisions.md:
# Decisions
Technical decisions and their rationale. Know why before you change.
---
discoveries.md:
# Discoveries
How things work in this codebase. Tribal knowledge, written down.
---