Lessons - how it gets better each sprint

A lesson that stays in the retrospective that wrote it is read by nobody after that sprint. The tooling’s own comment on the function that moves them is the clearest statement of the problem:

Without this, the retro is a diary.

Two tiers, and the default is local

Per-project. A lesson learned here stays here. It is the default, because a lesson learned on your project is not automatically true on any other. Agentic waves load it at wave start and inject it into every agent prompt as known pitfalls on this project.

Cross-project. The skill ships its own registry of generalisable engineering and process lessons - the ones that improve decisions on any project at all. A brand-new project inherits it on day one, before it has made a single mistake of its own.

/sdlc-studio lessons add              # a lesson for this project
/sdlc-studio lessons add --global     # promote it - the deliberate act, not the reflex
/sdlc-studio lessons recall           # anything we should know before deciding this?
/sdlc-studio lessons list
/sdlc-studio lessons revalidate       # which of these still hold?
/sdlc-studio lessons summary
/sdlc-studio lessons prune --older EP0003

Note

A project-specific fact - a config path, a box name, an incident - is memory, not a lesson. Lessons are things that change a decision.

Promotion needs a version-controlled destination. Without one it is refused rather than written into a copy the next update deletes.

The loop is gated, not hoped for

Five rungs, and three of them fail a gate:

1. The retro exists. The gate fails until the batch’s retrospective is on disk.
2. Its lessons are lifted. retro extract moves them into the store, titled from the first sentence rather than the first physical line - a headline cut mid-clause is one the next sprint skims past. It is idempotent by content, so re-running converges rather than duplicating.
3. Open lessons are re-validated - gated. The gate fails while any open lesson sits past its validity horizon, or carries none at all. The log cannot silently grow into unread noise.
4. The rolling summary is refreshed - gated. A lesson closed since the last regeneration fails it exactly as an added one does.
5. The next plan reads it - emitted, not requested. sprint plan prints the still-valid lessons inside the plan itself. It does not point at a file the agent may not open.

That last rung is the one that makes the difference. The batch you approve already contains the lessons the last sprints paid for.

Recall is also how an audit starts

Before an audit fans out, the ranked lessons are read first - because a lesson this project already paid for is a lens. What went wrong last time is where to look first.

And the estimate learns too

The same principle runs through the forecast. Every project starts on a shipped default rate. Once it has five units of its own measured evidence, its own numbers replace the default - and the plan always says which of the two it is quoting.

A rate re-fitted to one or two units is fitting noise. This project has twice had to delete a rate that hardened into an article of faith, which is why the threshold exists and why nothing is allowed to hard-code it.

Where to next

• The retrospective - where lessons come from.
• Sprint planning - where they are printed back.
• Audit - where they become lenses.