Skip to content

evolution.md

Latest commit

 

History

History
221 lines (165 loc) · 7.45 KB

evolution.md

File metadata and controls

221 lines (165 loc) · 7.45 KB
Raw

Concept — Architecture Evolution

The architecture itself must evolve, and it must avoid relying on bitter lessons to drive iteration. This document describes the two-loop evolution mechanism.

Two loops

┌─ Fast loop (in-project) ─────────────────────────────────┐
│                                                          │
│  TaskCompleted / periodic → /retro → candidate ADRs →    │
│  project ADRs                                            │
│                                  ↑              ↑        │
│                                  user review    0001+    │
└──────────────────────────────────────────────────────────┘
                       ↓
                       ↓ (same pattern recurring across projects, 3+ times)
                       ↓
┌─ Slow loop (cross-project) ──────────────────────────────┐
│                                                          │
│  /promote-adr → scan all projects' ADRs → cluster        │
│  → promote into spec/templates/ or spec/docs/adr/        │
│  ↑ quarterly                                             │
│                                                          │
└──────────────────────────────────────────────────────────┘

Fast loop: /retro

Trigger options

Trigger Frequency Recommended use
/retro manual on demand mandatory default
periodic cron hook weekly long-term projects
PR merged hook per PR projects with PR flow
TaskCompleted per task don't install (too dense, noisy)

The "don't install TaskCompleted" choice is deliberate — see ADR-0002 principle 1 ("default to silence").

/retro flow

1. Collect from a recent window (default 7 days):
   - handoff archive
   - commits / PRs
   - existing ADRs

2. Spawn a retro subagent (read-only — no Edit/Write) with
   this prompt:
   "Review work from this window. Identify:
    (a) patterns recurring but not yet in an ADR
    (b) operations contradicting an existing ADR (signal that
        the ADR needs update or retirement)
    (c) one-off events (don't record)
    Output format: candidate-ADR list, each citing evidence
    (handoff id / commit hash)"

3. Present the candidate list to user

4. User picks per item:
   [promote to ADR / ignore / watch again]

5. Write selected ADRs, bump numbering

Key disciplines

  • retro subagent has no Edit/Write — it can suggest but not modify
  • ADRs are project memory; a human must confirm; an agent must not unilaterally rewrite history
  • /retro simultaneously audits auto memory (see auto-memory.md)
  • /retro simultaneously checks INDEX freshness

Slow loop: /promote-adr (cross-project meta-evolution)

Trigger options

Quarterly (or whenever a pattern feels like it's recurring across 3+ projects):

/promote-adr

Flow

1. Scan all projects on the machine (default ~/code/)'s docs/adr/

2. Have an LLM cluster all ADRs by topic:
   "decisions appearing in ≥3 projects and pointing the same way"

3. Output candidate list, each item labeled with:
   - projects it appears in
   - first appearance time
   - original triggering scenario

4. User picks per item:
   ✅ promote → modify spec's templates or docs/adr/, bump spec version
   ⏸ watch again → mark, revisit later
   ❌ project-specific → ignore

Effect of a promotion

Promoted spec does not auto-update existing projects (to avoid breaking the status quo). But new projects bootstrapped later get the new version. To apply a new rule to old projects, run /bootstrap-agents --upgrade separately.

Same shape as /retro at a higher level

Note the structural similarity:

  • /retro: read project's handoffs/commits/ADRs → produce ADRs
  • /promote-adr: read cross-project ADRs → produce spec upgrades

Same "retrospective" pattern, different scope.

Why this two-loop design avoids bitter lessons

Traditional model:

hit pain → feel bad → recall it later → tweak architecture from memory
            ↑           ↑                ↑
         may forget   may stop hurting  may misremember

Two-loop model:

hit pain → handoff/commit captures evidence → /retro LLM identifies → ADR
                                              ↑                      ↑
                                           not human memory       decision history
        ↓
        multiple projects hit it → /promote-adr LLM identifies → spec upgrade
                                    ↑                            ↑
                                 not cross-project memory     permanently captured

Key: bitter-lesson "lessons" get machine-assisted identification, not human-memory.

Discipline of evolution

ADRs are never deleted

A superseded ADR gets labeled superseded-by-NNNN, never removed.

  • Future readers can follow the chain to see "why we decided that, why we changed"
  • ADR history is the project's evolutionary DNA

Spec upgrades write CHANGELOG

Every spec upgrade (whether /promote-adr-triggered or manual) gets a CHANGELOG entry in the spec repo:

[2026-09-01] v0.2 — handoff schema adds cost-estimate field
Added: handoff TEMPLATE adds estimated-cost field
Source: 3 projects repeatedly hit "executor done before realizing
        cost went over budget"
Decision: docs/adr/0011-cost-estimation.md (promoted from
          project-level ADRs)

Backward-incompatible spec changes get an explicit supersede

If spec v0.2 isn't backward-compat with v0.1 (e.g., a required handoff field changed), write a superseding ADR explaining why compat is broken, and provide a migration guide.

Don't "silently change behavior" — that's the source of cascade effects.

How /retro and /promote-adr land

These are slash command concepts. In v0.1 spec they have only "what they should do" descriptions, no executable implementations.

Expected landing path:

  • v0.x: run them manually (spawn a subagent, paste the prompt)
  • v0.x → v1.0 (plugin): make them slash commands; typing /retro auto-spawns the subagent

FAQ

Q: /retro didn't surface the pattern I was thinking of — what now? LLM-as-judge isn't truth. /retro is assist, not judge. Patterns you already see: write the ADR directly, no need to wait for /retro. /retro's value is "surfacing what you didn't see."

Q: /promote-adr cross-project scanning might expose sensitive project info — what now? By default scans only the directory you point it at (~/code/), no external transmission. Exclude sensitive projects via --exclude.

Q: This feels bureaucratic for a personal project — do I really need it? ADR-0002 #4 ("pay-as-you-go") applies — small projects can run just /retro, skip /promote-adr, even skip both. But the goal itself — avoid bitter-lesson-driven iteration — is worth some ceremony.

See also