# 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