Diff v1 → v2

  # 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
  
  ```mermaid
  flowchart LR
-     V["/verify/ PASS"] --> RE["/retrospective/"]
+     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["/constitution/<br/>promote to rule"]
+     R -- yes --> CON["/speckit.constitution/<br/>promote to rule"]
      R -- no --> Wait[Stay pending]
  
-     SE --> EX["/extract-skills/"]
+     SE --> EX["/speckit.agentic.skills/"]
      EX --> SK["skills/extracted/*.yml"]
  
-     SK -.->|next run uses| Specify["/specify/"]
-     CON -.->|next run respects| Plan["/plan/"]
+     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.
  
  ```yaml
  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.
  
  ```yaml
  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 `/constitution`. It becomes an enforced rule, checked by future plans and verifies.
+ `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:
  
  ```yaml
  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: empty constitution, empty skills library. Fine. Each run adds a few. By run ~10 you have ~5-10 rules and ~10-20 skills. The slope is the value, not the starting point.
+ 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.