# Promotion And Prevention

Retrospective preserves reusable learning and prevention follow-up.

## What To Inspect

Inspect the smallest set that explains the work:

- the originating ticket, plan, research, audit, evidence, worker output, or changed record
- acceptance criteria, findings, evidence, and residual risks
- worker output and reconciliation notes when a worker ran
- changed files or diffs when implementation shape matters
- repeated questions or operator corrections when they show reusable friction

Do not rely on chat recall when the records can show what happened.

## Distill The Lesson

Ask:

- What should future agents know before doing similar work?
- What mistake should not recur?
- What source, command, path, or record should be easier to find?
- What intended behavior, strategy, or judgment changed?
- What evidence now supports or challenges a claim?
- What follow-up is concrete enough for a ticket?
- What risk still needs audit?

Keep one-time execution detail out of durable records unless it explains a future
decision, procedure, or prevention route.

## Route By Shape

Promote to knowledge when the lesson is reusable explanation, procedure,
preference, troubleshooting, atlas, entity context, or retrieval cue.

Promote to research when the lesson is an investigation result, rejected path,
tradeoff, null result, source comparison, or bounded conclusion.

Promote to specs when the lesson clarifies intended behavior, interface contract,
requirement, scenario, or invariant.

Promote to plans when the lesson changes decomposition, sequencing, rollout,
dependency, or recovery strategy.

Promote to constitution when the lesson changes durable project judgment,
principle, constraint, ADR, or roadmap direction.

Promote to evidence when the lesson depends on an observed artifact, validation
output, reproduction, log, screenshot, scan, or command result that should remain
inspectable.

Create or update a ticket when the lesson is executable follow-up work.

Use audit when a claim, risk, evidence gap, implementation shape, or closure story
needs Ralph-backed challenge.

Promotion identifies the owning surface; it does not bypass that surface's
procedure or authority gate. Before changing specs, plans, constitution, or
research synthesis, use the owning skill and pause for operator authority when the
lesson changes intended behavior, strategy, durable judgment, or conclusions.

## Promotion Quality

A good promotion is:

- findable by likely future task words
- narrow enough to use without rereading the whole work thread
- honest about what was observed and what remains unproven
- linked to source records or evidence when that clarifies use
- placed in one primary surface where possible

When a lesson touches several surfaces, put the durable claim in the surface that
can maintain it and add lightweight related-record links where useful.

## Prevention Quality

A prevention artifact should reduce a real future failure mode.

Good prevention examples:

- knowledge troubleshooting for a repeated diagnosis path
- knowledge procedure for a repeated manual workflow
- research null result for a tempting but rejected path
- evidence record for a validation observation future agents may need
- spec clarification for ambiguous intended behavior
- follow-up ticket for concrete missing work
- audit record for unresolved risk or unsupported claims

Skip prevention artifacts for ordinary noise. If the lesson is too local, too
uncertain, or already obvious in an easy-to-find record, record no durable
follow-up.
