compounding

Compounding

Overview

Capture at most one useful repository-specific lesson from completed work. Retrieval is the goal: update the closest existing lesson before adding another, and write nothing when the result would be noise.

Qualify the Lesson

Use the completed diff, tests, review, and debugging evidence. A lesson qualifies only when it is both non-obvious and reusable in this repository.

Write nothing for:

• a trivial fix;
• standard practice an engineer should already know;
• a cross-repository generality that is not specific to this repository.

Capture at most one lesson per completed work or implementation. When several facts qualify, choose the lesson most likely to prevent repeated investigation or error here.

Search Before Writing

1. If docs/learnings/README.md exists, read that index first.
2. Open only notes whose index summaries are relevant to the candidate lesson.
3. Update the closest existing lesson before creating a new note.

When the index is absent, do not treat an unindexed directory scan as a substitute. Continue only if the completed work itself produced a qualifying lesson.

Write One Flat Lesson

Keep every note directly under docs/learnings/; never create category subdirectories. Use learning-template.md with exactly these fields: Context, Lesson, When It Applies, Evidence or Example, and Related Lessons. Keep the note short and cite concrete repository paths, commands, tests, or behavior when useful.

Create docs/learnings/README.md only when a qualifying lesson requires the first write. The index lists each note as a link with a one-line summary. Update the index in the same change that creates or updates the lesson.

Respect Ownership Boundaries

Compounding never uses docs/solutions, creates category folders, or writes instructions, policy, AGENTS.md, or CLAUDE.md. It does not write or edit a glossary or ADR.

When the candidate is really a domain term or architectural decision, stop the Compounding write. Route it to nicopowers:domain-modeling only after explicit user authorization; Domain Modeling alone owns glossary and ADR artifacts.