v1.7.0 ·
The framework that learns from itself: retrospectives and the lessons layer
Nothing in AIDLC learned from finished work. Every instance ended and its lessons evaporated: what surprised me, what took longer than estimated, which phase let the defect through. Gates, adversarial review and testing all worked on one instance at a time. Nothing worked across instances. And cost tracking, shipped a few days earlier, made the gap worse. The ledger recorded what each instance cost, but with no feedback loop that data was trivia, not calibration.
What changed
Finishing an instance now triggers a retrospective on its own. It is capped at one round-trip, so it stays a prompt and not an interrogation. It runs once: a marker and a check for an existing retrospective file stop a repeated transition from firing it twice. When the instance finishes in a worktree about to be removed, the retrospective runs before the cleanup, so the lessons survive.
What it finds lands in .aidlc/guidance/lessons.md. The phase skills read that file at run time, so a lesson learned today changes tomorrow's requirements prompt with no recompile. It is append-only. A lesson that turns out wrong is retracted by adding a note, never by editing history. Writes go to a temp file, get renamed, and are read back. The file also carries a merge=union rule, so two sessions finishing at once both keep their lessons. Past 25 sections or 90 days, aidlc status suggests consolidating.
A bugfix can now record what caused it. The reproduction step proposes candidates from git blame, the knowledge graph and the instance registry, and asks instead of guessing. Declining is a valid answer. The field takes a list, because one defect can have more than one origin.
All of it feeds aidlc metrics: change failure rate per template, lead times per phase and per instance, and true cost, meaning a feature's own cost plus the cost of the bugfixes it caused, followed one level deep. Where data is missing it shows null, not zero. That is the difference between "this feature was free" and "nobody measured". The command never writes state.
Why this way
I weighed three shapes. A minimal loop, with a retro skill and the cause field but no metrics command, would have left the numbers invisible, because "on demand" means "never". A lessons file alone was the safest slice, but it defers the measurement, and a lessons file nobody consolidates becomes a second backlog. I chose the full loop and took the write-back design from the lessons-first option.
What it cost
It shipped as v1.7.0 across 63 files and 2756 added lines, with the CLI and content packages in lockstep. It also added a new thing every instance has to pass through. Whether the lessons file stays useful depends on someone consolidating it.