The Compounding Loop

The Invisible Cost of Skipping Retro

Every merged PR in spec-driven development contains more than code. It contains information: what worked about the spec, what the agent struggled with, what the review caught that the spec missed, what the quality gate blocked. This information is valuable precisely because it improves the next spec.

The retro is the mechanism that extracts this value. Without it, the information evaporates — locked in a context window that will be closed in hours, unavailable to future sessions, repeated as mistakes in the next delivery cycle.

The Five-Step Loop

The most important observation in this loop: Phase H (Compounding Loop) in the /ship meta-orchestrator is not optional. The skill is structured so that Phase G (PR + Notify) → Phase H (Compounding Loop) → next spec pre-improved. In single-user foreground sessions, Phase H fires automatically. In multi-sector orchestrator sessions (/ship-prd), it is on-demand via --review-proposals.

The retro that doesn't happen is the most expensive thing in spec-driven development. It costs nothing in the short term. It costs compounding growth in the medium term.

The lessons.md Format

The lessons.md file in each project root captures reusable patterns, anti-patterns, and discovered conventions. The format matters because vague lessons don't prevent recurrence:

## 2026-05-31 — Spec-Driven / Consumer Contracts

**Mistake**: Changed getAllAcademyArticles() return shape without grepping callers.
**Root cause**: Assumed only the lesson page called the function; forgot the AI tutor corpus ingest.
**Rule**: Before finalizing any output shape: `grep -rn "getAllAcademyArticles" $(git ls-files)`. 
List every call site in the PRD consumer contracts section before dispatch.

Three fields. What went wrong — specific enough to recognize if it recurs. Root cause — why it happened, not just what happened. Rule — the specific, actionable step that prevents it.

The rule from CLAUDE.md: "After ANY correction from Knox, create/update lessons.md... If a lesson keeps appearing, the rule isn't strong enough. Escalate it to CLAUDE.md or MEMORY.md." Lessons that repeat are rules that weren't strong enough. The escalation path exists to enforce this.

Semantic Memory Layer Memory: Cross-Session Recall

lessons.md captures per-project learning. Semantic Memory Layer captures cross-project, cross-session learning. The distinction matters when a pattern learned in the academy project is relevant to a trading-bot problem three weeks later.

After adding a lesson to lessons.md, the memory_remember call stores it with searchable metadata:

# After lessons.md update
memory_remember(
  content="Consumer contract check: grep callers before finalizing output shape. 
           Found case in academy where AI tutor ingest broke on getAllAcademyArticles() shape change.",
  metadata={project: "academy", category: "spec-driven", tags: ["consumer-contract", "output-shape"]}
)

Three weeks later, when a trading-bot session encounters an output shape change:

memory_query("consumer contract output shape")
# → surfaces the academy lesson: "grep callers before finalizing output shape"

The lesson jumps repositories. This is how the compound learning curve works across an ecosystem of dozens of repos — not by writing everything down in one document, but by making lessons searchable across context windows.

The Spec-Impl Decoupling Trap

The compounding loop has one failure mode that is structurally separate from the retro: the spec-impl decoupling coverage gap.

This trap is subtle. You spec a feature with great care. You merge the spec. The implementation seems obvious. Three sessions pass. The spec sits in docs/prd/ with no corresponding implementation. The feature never ships.

The rule: every spec-phase completion creates its impl ticket in the same conversation. Not later. Not when you remember. In the same conversation, before you close the terminal window.

The ticket goes into kanban-state.json. It references the PRD. It has an explicit status: "in-queue." The kanban board is the source of truth for what is actually committed to ship.

The Retro-Lessons-Memory Chain

The three steps that preserve learning across sessions form a chain that is only as strong as its weakest link:

1. Retro (/retro skill) → produces session narrative: what happened, what was built, what failed
2. lessons.md update → converts session narrative into specific, actionable rules
3. memory_remember → stores rules to Semantic Memory Layer with searchable metadata

Break any link and the compound learning stops at that point. The most common break is step 2 → 3: lessons are written to lessons.md but never stored to Semantic Memory Layer. They remain available locally but cannot be recalled cross-session.

The discipline: after every lessons.md update, run memory_remember for every non-trivial rule. The overhead is minutes. The compounding value is sessions.

What's Next

The next lesson assembles everything into the end-to-end playbook: idea → research → PRD → decompose → build → gate → review → ship → retro. With the full audit lab checklist that makes each step verifiable.