| # Learnings |
|
|
| This directory is the system-of-record for durable learnings extracted from completed work. |
|
|
| ## Policy |
|
|
| - Prefer merging/deduping into existing bullets over adding new near-duplicates. |
| - Keep each category within the configured bullet budget (default: 30 per category). |
| - Each learning bullet should end with a source suffix: `*(F024)*` for internally-derived learnings, or `*(Author, Source Year)*` for externally-sourced insights. |
| - Archive overflow in `docs/learnings/archived/` rather than growing unbounded. |
| - Use one-line bullets only, starting with `- `. |
|
|
| ## Categories |
|
|
| | Category | File | Scope | |
| |----------|------|-------| |
| | Architecture | [architecture.md](architecture.md) | System structure, patterns, boundaries | |
| | Conventions | [conventions.md](conventions.md) | Naming, file organization, code style | |
| | Workflow | [workflow.md](workflow.md) | Process, automation, verification | |
| | Integrations | [integrations.md](integrations.md) | APIs, libraries, external systems | |
| | Gotchas | [gotchas.md](gotchas.md) | Non-obvious behaviors, edge cases | |
| | Security | [security.md](security.md) | Threats, hardening, secrets | |
| | Testing | [testing.md](testing.md) | Test patterns, fixtures, mocking | |
|
|
| ## Archive |
|
|
| Learnings that are stale or superseded move to [archived/README.md](archived/README.md). |
|
|
| ## Adding Learnings |
|
|
| The `compound-engineer` agent updates these files after completed features. To add learnings manually: |
|
|
| 1. Find the appropriate category file |
| 2. Add a one-line bullet starting with `- ` |
| 3. End with a source: `*(F001)*` for feature-derived learnings, or `*(Author, Source Year)*` for external insights |
| 4. If category is at budget, merge related learnings or archive stale ones |
|
|
