Lessons Learned

Lessons Learned

Turn completed work into practices that improve similar future work. A lesson must change future behavior or explicitly justify no change.

Boundary

Use this skill when work is complete, a problem is resolved, or an experiment has produced enough evidence to compare expectations with results.

Do not use it to:

• choose among options that are still open
• judge whether a consequential decision was rational given what was known at the time
• assign blame or infer a person's motives
• write a chronology without extracting reusable guidance
• declare a lesson while the outcome or cause remains unknown
• create or maintain a repository knowledge store unless the user requests that artifact

Completed work can include decisions, but this skill evaluates what the work teaches. It does not audit decision quality.

Required Inputs

Collect the available evidence for:

• intended outcome and scope
• actual outcome
• important actions, constraints, and changes during execution
• expected and unexpected effects
• failures, recoveries, and successful practices
• verification, measurements, feedback, or other outcome evidence
• unresolved unknowns

Separate contemporaneous records from later recollection. Missing evidence narrows the lesson and confidence.

Workflow

1. Establish the evidence boundary

List what is directly observed, what is reported from memory, what is inferred, and what remains unknown.

Do not treat a later outcome as proof that an earlier action caused it. Name competing explanations when the evidence cannot distinguish them.

2. Compare intent with outcome

State:

intended outcome -> actions and conditions -> observed outcome

Identify where the result matched, exceeded, or missed the intent. Include useful unexpected results. Do not treat every difference as a failure.

3. Identify candidate lessons

For each candidate, ask:

• What evidence supports it?
• What mechanism explains the result?
• Under what conditions should it apply?
• What would make it false or unsafe to reuse?
• Does it change a future action, check, or stopping rule?

Reject generic statements such as "communicate better," "test more," or "plan earlier" unless the evidence supports a specific practice and trigger.

4. Convert lessons into future practices

Classify each supported lesson as one of:

• Repeat: preserve a practice that contributed to the result.
• Change: modify a practice that caused avoidable cost or failure.
• Stop: remove a practice whose expected value was not supported.
• Add evidence: collect a missing signal before making the same inference again.
• No change: keep the current practice because the evidence does not justify a change.

For each practice, state where it applies and where it does not. Avoid turning one event into a universal rule.

5. Choose the output location

Return the lessons in the conversation unless the user requests a durable artifact or the project provides an explicit location and format for one.

When writing an artifact:

• use the requested or established project location
• update an existing relevant artifact instead of creating a duplicate when practical
• include the evidence and applicability boundary with each lesson
• do not edit instructions, code, or unrelated documentation automatically

Output

1. Work reviewed: scope, intended outcome, and actual outcome
2. Evidence boundary: observed facts, recollections, inferences, and unknowns
3. Lessons: evidence, mechanism, applicability, and confidence
4. Future practices: repeat, change, stop, add evidence, or no change
5. Artifact: path when one was requested and written

If the evidence supports no reusable lesson, say so. Do not create a lesson to make the exercise appear productive.

Quality Gate

• The work is complete enough to support reflection.
• Each lesson cites evidence and a plausible mechanism.
• Outcome and causation are not treated as the same thing.
• Each supported lesson changes a specific future practice or justifies no change.
• Applicability limits and unknowns remain visible.
• The result does not duplicate a decision-process retrospective.
• No durable artifact or repository change occurs without a requested or established destination.