Skip to content

v1.7.0 ·

The framework that learns from itself: retrospectives and the lessons layer

The problem

Nothing in AIDLC learns from finished instances. Every instance ends at Maintenance and its lessons evaporate: what surprised us, what took longer than estimated, which phase leaked the defect. The framework has per-instance quality mechanisms (gates, adversarial review, testing) but no system-level one — no measurement across instances and no institutional memory. Cost tracking (shipped 2026-08-16) makes this gap acute: the ledger records what each instance cost, but with no feedback loop the data is trivia rather than calibration.

How it could be solved

Option A — Minimal loop: retro skill + caused_by field, metrics ad hoc

New aidlc-retrospective skill fired by an on-instance-complete action; caused_by added to the bugfix reproduction flow. Metrics have no dedicated surface — agents compute them on demand by reading state.

  • ✅ Smallest footprint; ships the compounding behavior (write-back) immediately.
  • ✅ No new CLI surface to document/maintain.
  • ❌ Metrics stay invisible in practice — "on demand" means "never"; nobody discovers roll-ups without a command.

Option B — Full loop: retro skill + caused_by + aidlc metrics command

Everything in A, plus a metrics module (packages/cli/src/metrics/) computing DORA-style roll-ups from state, with aidlc metrics (and --json for CI/web). Mirrors how aidlc cost report made the cost ledger legible.

  • ✅ Metrics become a first-class, discoverable surface; natural consumer of cost + traceability data.
  • ✅ --json output feeds the future VS Code extension / web dashboard for free.
  • ❌ Larger scope: report design, template roll-ups, edge cases (instances predating caused_by).

Option C — Lessons-layer-first: dedicated lessons.md guidance layer, defect linkage deferred

Retro writes to a dedicated append-only guidance layer (.aidlc/guidance/lessons.md) with periodic consolidation; caused_by/metrics deferred to a follow-up instance.

  • ✅ Safest write-back story (no context-doc rot); smallest first slice.
  • ❌ Defers the measurement half — the DORA metrics are what make cost data actionable, and the two halves reinforce each other.
  • ❌ A lessons file nobody consolidates becomes a second backlog.

Chosen direction (user-confirmed 2026-08-17): Option B — the full loop — with Option C's write-back mechanism (see D2). One new metrics module + command, retro skill wired via lifecycle actions, defect linkage in bugfix reproduction.

How AIDLC solves it

A closed feedback loop for the lifecycle: the framework now learns from the work it finishes instead of forgetting it. Three mechanisms, each filling a gap where a completed instance used to leave nothing behind.

Retrospectives that actually fire. Completing an instance now triggers a retrospective automatically. The trigger is the completion moment — derived from the template and scope rather than hardcoded, so a maintenance-terminal template completes on maintenance entry (maintenance is open-ended and would otherwise never close) while a deployment-terminal one completes on deployment exit. The retrospective is capped at one round-trip so it stays a prompt rather than an interrogation, and it is idempotent: a marker plus a retrospective.md existence check means re-running a transition never fires it twice. When an instance completes in a worktree that is about to be removed, the retrospective runs before the cleanup, so the lessons survive the worktree.

A lessons layer that accumulates. Retrospective findings land in .aidlc/guidance/lessons.md, a guidance file read at runtime by the phase skills — so a lesson learned today changes tomorrow's requirements prompt with no recompile. Lessons are append-only with immutable frontmatter: a superseded lesson is retracted by appending, never by editing history. Writes go through temp-then-rename with a read-back verification, and the file carries a merge=union gitattribute so two sessions finishing concurrently both keep their lessons instead of one clobbering the other. Past a threshold — 25 sections or 90 days — aidlc status starts suggesting consolidation, which runs only from the primary checkout and confirms every edit individually.

Defect linkage, so cost has a denominator. A bugfix instance can now record what caused it. The Requirements phase for the bugfix template gained a reproduction flow that proposes caused_by candidates — drawn from git blame, the knowledge graph, and the instance registry — and asks rather than guesses. Declining is a first-class answer; a self-reference is rejected. The field is list-valued, because one defect can have more than one origin.

aidlc metrics. All of the above feeds one new command reporting change failure rate per template, lead times per phase and per instance, and true cost — a feature's own cost plus the cost of the bugfixes it caused, followed one level deep. It degrades to null rather than 0 when data is genuinely absent, which is the difference between "this feature was free" and "nobody measured." Reads are byte-identical: the command never mutates state.

Both packages shipped in lockstep as v1.7.0 — @rasensio/aidlc and @rasensio/aidlc-content — across 63 files, +2756 lines.