Showing version 2 bot legacy · api · 2026-07-28T06:30:55Z

The Compounding Layer

The Compounding Layer

The pipeline produces one feature, well, once. It also produces lessons: what went wrong, what worked, which failures recurred, which patterns are now reusable. If those lessons evaporate at the end of each run, every future run pays the same costs.

The compounding layer captures lessons and feeds them back. Failures compound into rules. Successes compound into reusable skills.

Flow

flowchart LR
    V["/speckit.agentic.verify/ PASS"] --> RE["/speckit.agentic.retrospective/"]
    RE --> CA[CONSTITUTION_AMENDMENTS]
    RE --> SE[SKILLS_TO_EXTRACT]

    CA --> KF["known-failures.md<br/>count"]
    KF --> R{3+ times?}
    R -- yes --> CON["/speckit.constitution/<br/>promote to rule"]
    R -- no --> Wait[Stay pending]

    SE --> EX["/speckit.agentic.skills/"]
    EX --> SK["skills/extracted/*.yml"]

    SK -.->|next run uses| Specify["/speckit.specify/"]
    CON -.->|next run respects| Plan["/speckit.plan/"]

Retrospective

After verify passes, retrospective reads the whole run (spec, plan, tasks, diff, verify report) and outputs two structured blocks:

CONSTITUTION_AMENDMENTS — proposed rules that, if adopted, would prevent the failures seen this run.

CONSTITUTION_AMENDMENTS:
  - id: cache-stateless-builders
    rationale: |
      Chroma formatter was constructed per HTTP request, costing ~3ms per call.
    rule: "Stateless objects with non-trivial construction cost should be cached
            at handler init, not constructed per request."
    severity: warn

SKILLS_TO_EXTRACT — reusable patterns from this run.

SKILLS_TO_EXTRACT:
  - name: sqlite-fts5-pattern
    rationale: This run set up an FTS5 virtual table with content/content_rowid
      and triggers — the canonical pattern.
    template_path: skills/extracted/sqlite-fts5-pattern.md

Known-failures funnel

A single proposed amendment is not enough. One observation might be a one-off. Three is a pattern.

known-failures.md
==================
- id: cache-stateless-builders    count=3   first=2026-03  last=2026-06
- id: never-amend-shipped         count=1   first=2026-06
- id: ctx-too-tight               count=2   first=2026-04  last=2026-05

count >= 3 → next retrospective promotes via /speckit.constitution. It becomes an enforced rule, checked by future plans and verifies.

False positives stay pending forever — cheap. False negatives surface on the next recurrence.

Debt ledger

The other input to the funnel. When an agent knowingly cuts a corner with a real ceiling — a global lock, an O(n²) scan, a naive heuristic — it leaves an agentic:debt comment naming both the ceiling and the trigger to revisit it. /speckit.agentic.debt harvests every marker in the tree into one ledger.

internal/cache/store.go:88
  simplified: global lock instead of striped
  ceiling:    fine under ~50 rps
  upgrade:    when write contention shows in p99

internal/parse/tokens.go:212           [no-trigger]
  simplified: O(n²) scan over token list
  ceiling:    inputs under ~2k tokens
  upgrade:    —

Markers tagged no-trigger are the dangerous ones: a ceiling with no revisit condition will not be revisited. And if the same ceiling shows up in three or more places, it stopped being a shortcut — the codebase adopted an architectural constraint by accident, which is a constitution amendment, not a debt row.

A deliberate shortcut is fine. An unrecorded one is how a codebase acquires limits nobody remembers agreeing to.

Skills library

Skills live under skills/extracted/*.yml. The agent receives a digest of relevant skills at the start of each run. Shape:

name: sqlite-fts5-pattern
trigger: "adding full-text search to a new SQLite table"
applies_when:
  - "table has a text/title column to index"
  - "soft-delete is not required"
template: |
  CREATE VIRTUAL TABLE <name>_fts USING fts5(
    title, content, content=<name>, content_rowid=id
  );
  -- + ai/ad/au triggers
references:
  - internal/storage/sqlite.go:24-63

Trigger + preconditions + template + references. Snippets without scaffolding are not skills, just text.

Why it matters

Without compounding, every run is independent:

Run 1: 100% effort
Run 2: 100% effort
Run 3: 100% effort

With compounding:

Run 1: 100% — produces 3 rules + 2 skills
Run 2: 95%  — rules + skills now help
Run 3: 90%

Marginal cost trends down. Marginal quality trends up. Previous failure modes can no longer recur — the constitution forbids them.

This is also where Agentic Engineering differs from "let the AI code for me." The system gets better at your codebase over time, even though the underlying model didn't change.

Anti-patterns

  • Skip retrospective when in a hurry. Highest-leverage phase, skipped. Cost is invisible per run, enormous over a quarter.
  • Promote every observation to a rule. Floods the constitution; future plans drown in noise. The 3-count threshold filters one-offs.
  • Treat the constitution as a wishlist. It's enforced. Plans that violate it must justify in Complexity Tracking. Verifies that detect violations are BLOCKERs.

Bootstrap

Day one: a baseline constitution and an empty skills library. The extension ships a starting rulebook — process, decomposition, restraint, and quality rules covering the failures this methodology sees most often — so the promotion machinery has somewhere to promote into. Copy the rules you actually want to enforce; a rulebook nobody enforces trains everyone to ignore it.

Each run adds a few. By run ~10 you have ~5-10 rules and ~10-20 skills, and the ones you earned from your own retrospectives outrank anything shipped in the box. The slope is the value, not the starting point.

Successes compound into the skills library. Failures compound into the constitution. Everything else is noise.