Retrospective
Turn execution experience into institutional knowledge. This skill orchestrates a fixed
Phase 0 through Phase 5 workflow that gathers evidence, generates insights, diagnoses root
causes, decides actions, scores atomicity, and persists learnings. The long-form rubrics
live verbatim in references/; this file is the orchestration contract.
This skill owns the long-form rubrics the retrospective agent loads from references/.
It is callable from Skill("retrospective") and from /retro fill <date>.
The Stop hook that once invoked it automatically was deleted, so a
retrospective is written when someone asks for one.
Triggers
| Trigger Phrase |
Operation |
run a retrospective |
Full Phase 0..5 workflow over the given scope |
retro fill |
Fill an unfilled auto-retro skeleton for a date |
extract learnings from this session |
Phase 0..4 over the current session |
diagnose this failure |
Phase 0..2 root-cause analysis, then stop |
what did we learn |
Phase 4 atomicity-scored learning extraction |
When to Use
| Situation |
Use This Skill? |
A reflect pass produced a HIGH-confidence finding |
Yes |
main went red, or a merge was reverted or force-fixed |
Yes |
| The user corrected the work explicitly |
Yes |
| A session ended and nothing above fired |
No, a calendar is not a trigger |
An unfilled auto-retro skeleton exists in .project-toolkit/retrospective/ |
Yes (fill it) |
| Diagnosing why a task failed (Five Whys, fishbone) |
Yes |
| Capturing a single in-conversation correction ("no", "wrong") |
No, use reflect |
| Saving a quick checkpoint with no analysis |
No, use /checkpoint |
The output artifact is a Markdown file. The Learning Extraction Template in
references/learning-template.md defines the exact structure. Save to
.project-toolkit/retrospective/YYYY-MM-DD-[scope].md. Nothing writes new auto-retro
skeletons: the Stop hook that produced them was deleted. Skeletons
already on disk are historical and still fillable; when filling one, write to
its existing YYYY-MM-DD-auto-retro.md.
Inputs
| Input |
Source |
Required |
| Scope |
User argument (session, task, date, PR) |
Yes |
| Session log |
.project-toolkit/sessions/ most recent for the period |
When available |
| Git history |
git log over the period |
When available |
| GitHub activity |
PRs and issues for the period (via the github skill) |
Optional enrichment |
Treat the session log as the system of record for what happened. Git history and GitHub
activity are derived evidence that corroborate or extend it. When a source is unavailable,
degrade gracefully: produce the artifact from the evidence you have and mark the missing
sections, never substitute invented data.
A session log or transcript you will read on more than one turn, or one too large to
read whole, costs its full size on every turn that carries it. Distill it once with
distill_artifact.py (usage: context-optimizer skill, Tool Details: Distill
Artifact) and use the digest to locate evidence. When it lacks a detail, search the
raw source for that detail and read the matching lines with their context.
Process
The workflow is six sequential phases. Phase 0 gathers facts. Phases 1 and 2 interpret them.
Phase 3 decides actions. Phase 4 extracts and scores learnings. Phase 5 persists them. Each
phase links to the rubric and template it uses. Run them in order; do not interpret before
you observe.
Phase 0: Data Gathering
Gather facts before interpretation. Observation precedes diagnosis.
- Run the 4-Step Debrief (Observe, Respond, Analyze, Apply): see
frameworks.md, 4-Step Debrief.
- Build the Execution Trace chronology: see
frameworks.md, Execution Trace Analysis.
- Run Outcome Classification (Mad, Sad, Glad): see
frameworks.md, Outcome Classification.
Evidence sources: the most recent session log under .project-toolkit/sessions/, git log for the
period, and optional GitHub activity through the github skill. Do not use raw gh.
Phase 1: Generate Insights
Make meaning from data. Look past symptoms to find causes.
- Five Whys is mandatory for every failure: see
frameworks.md, Five Whys.
- Fishbone Analysis for complex failures with multiple contributing factors: see
frameworks.md, Fishbone Analysis.
- Force Field Analysis when a pattern recurs despite knowing better: see
frameworks.md, Force Field Analysis.
- Patterns and Shifts for multi-session trends: see
frameworks.md, Patterns and Shifts.
- Learning Matrix for quick categorization when short on time: see
frameworks.md, Learning Matrix.
Phase 2: Diagnosis
Prioritize findings for action. Diagnostic priority order: critical error patterns, success
analysis, near misses, efficiency opportunities, skill gaps, traceability health. The full
priority order, traceability metrics, and diagnosis template live in
diagnosis-and-actions.md, Diagnosis.
For each root cause that Five Whys surfaces, store a root-cause pattern for future
prevention: see
diagnosis-and-actions.md, Root Cause Pattern Management.
If the work touched diagnosis or action classification, stop here for the diagnose this failure trigger; otherwise continue to Phase 3.
Phase 3: Decide What to Do
Move from insights to action.
- Action Classification (Keep, Drop, Add, Modify): see
diagnosis-and-actions.md, Action Classification.
- SMART Validation of every proposed learning before storage: see
diagnosis-and-actions.md, SMART Validation.
- Dependency Ordering of the resulting actions: see
diagnosis-and-actions.md, Dependency Ordering.
Phase 4: Learning Extraction
Transform insights into stored knowledge. Score every learning 0 to 100 percent for
atomicity and reject vague statements. The scoring rubric, quality thresholds, worked
examples, and evidence-based tagging live in
diagnosis-and-actions.md, Atomicity Scoring.
Assemble the artifact using the byte-exact
Learning Extraction Template. Save to
.project-toolkit/retrospective/YYYY-MM-DD-[scope].md. When filling an auto-retro skeleton, overwrite
the placeholder sections in the existing YYYY-MM-DD-auto-retro.md and remove the UNFILLED
banner.
Phase 5: Persist and Close
Persist learnings to memory and evaluate the retrospective itself.
- Persist learnings with atomicity at or above 70 percent to Serena memory (ADR-037). Search
for existing patterns before creating new entries to avoid duplicates: see
diagnosis-and-actions.md, Memory Protocol.
- Close with +/Delta, ROTI, and Helped, Hindered, Hypothesis: see
frameworks.md, Closing Activities.
- Record each actionable delta item in the artifact's
Findings for the owner table, classed
from the frozen completion contract: see
frameworks.md, Delta Triage. Do not file a
GitHub issue or write a backlog memory file. The owner decides what becomes tracked work.
Success Criteria
Before the retrospective is complete, confirm:
Boundaries
- This skill reads evidence and writes one artifact plus memory entries. It does not open PRs
or file issues; it lists delta items for the owner in the artifact.
- Memory and GitHub are integration points. A failed memory call degrades to a documented
fallback (write the artifact, note the memory write failed), never a silent context loss.
- Keep entry points thin. The Stop hook and
/retro fill parse inputs and call this skill;
they do not re-implement the workflow.
Scripts
| Script |
Purpose |
Exit codes |
scripts/run_retrospective.py |
Orchestrate Phase 0 to Phase 5 and write the retrospective artifact. |
0 artifact written; 1 a supplied learning scored below the persistence threshold (still written); 2 usage or configuration error; 3 unexpected external failure. |
scripts/extract_evidence.py |
Gather Phase 0 evidence (session log, git history) for the scope. |
0 evidence gathered (sources may be marked absent); 2 usage or configuration error; 3 unexpected external failure. |
scripts/score_atomicity.py |
Score a candidate learning against the 70% persistence threshold. |
0 at or above threshold; 1 below threshold (refine or reject); 2 usage or configuration error. |
References
- frameworks.md: Phase 0, 1, and closing activity rubrics
(4-Step Debrief, Execution Trace, Outcome Classification, Five Whys, Fishbone, Force Field,
Patterns and Shifts, Learning Matrix, +/Delta, ROTI, Helped/Hindered/Hypothesis).
- diagnosis-and-actions.md: Phase 2, 3, 4, and 5
rubrics (diagnosis priority and traceability, root-cause patterns, action classification,
SMART validation, atomicity scoring, evidence-based tagging, memory protocol).
- learning-template.md: the byte-exact Learning Extraction
Template that the output artifact must match.
- recursive-extraction.md: the agent's Phase 5 templates
(candidate list, delegation request, termination rules, artifact block).
- handoff-example.md: a filled example of the agent's
structured handoff block.
.claude/agents/retrospective.md: the agent that loads these references. The references
are the canonical home of the rubrics; the agent keeps only the gates and load conditions.
1---2name: retrospective-33description: Extract learnings from a session or task through structured retrospective frameworks. Gathers evidence, runs Five Whys and fishbone diagnosis, scores atomicity, and writes a canonical retrospective artifact. Use to turn execution experience into institutional knowledge. Use when you say "run a retrospective", "retro fill", or "extract learnings from this session". Do NOT use for in-conversation correction capture (use the reflect skill).4metadata:5 source: https://skillmd.com/skills/rjmurillo/retrospective-36---78# Retrospective910<!-- vendor-portability: declared. This skill reads the consumer's most recent session log under .project-toolkit/sessions/ as evidence and writes the retrospective artifact to .project-toolkit/retrospective/YYYY-MM-DD-[scope].md (creating the directory on demand). The session-log read is best-effort (the skill notes the source as absent when missing); the retrospective path is a write target. A vendored install without .project-toolkit/ gathers from git history alone and creates the output directory. -->1112Turn execution experience into institutional knowledge. This skill orchestrates a fixed13Phase 0 through Phase 5 workflow that gathers evidence, generates insights, diagnoses root14causes, decides actions, scores atomicity, and persists learnings. The long-form rubrics15live verbatim in `references/`; this file is the orchestration contract.1617This skill owns the long-form rubrics the retrospective agent loads from `references/`.18It is callable from `Skill("retrospective")` and from `/retro fill <date>`.19The Stop hook that once invoked it automatically was deleted, so a20retrospective is written when someone asks for one.2122## Triggers2324| Trigger Phrase | Operation |25|----------------|-----------|26| `run a retrospective` | Full Phase 0..5 workflow over the given scope |27| `retro fill` | Fill an unfilled auto-retro skeleton for a date |28| `extract learnings from this session` | Phase 0..4 over the current session |29| `diagnose this failure` | Phase 0..2 root-cause analysis, then stop |30| `what did we learn` | Phase 4 atomicity-scored learning extraction |3132---3334## When to Use3536| Situation | Use This Skill? |37|-----------|-----------------|38| A `reflect` pass produced a HIGH-confidence finding | Yes |39| `main` went red, or a merge was reverted or force-fixed | Yes |40| The user corrected the work explicitly | Yes |41| A session ended and nothing above fired | No, a calendar is not a trigger |42| An unfilled auto-retro skeleton exists in `.project-toolkit/retrospective/` | Yes (fill it) |43| Diagnosing why a task failed (Five Whys, fishbone) | Yes |44| Capturing a single in-conversation correction ("no", "wrong") | No, use `reflect` |45| Saving a quick checkpoint with no analysis | No, use `/checkpoint` |4647The output artifact is a Markdown file. The Learning Extraction Template in48`references/learning-template.md` defines the exact structure. Save to49`.project-toolkit/retrospective/YYYY-MM-DD-[scope].md`. Nothing writes new auto-retro50skeletons: the Stop hook that produced them was deleted. Skeletons51already on disk are historical and still fillable; when filling one, write to52its existing `YYYY-MM-DD-auto-retro.md`.5354---5556## Inputs5758| Input | Source | Required |59|-------|--------|----------|60| Scope | User argument (session, task, date, PR) | Yes |61| Session log | `.project-toolkit/sessions/` most recent for the period | When available |62| Git history | `git log` over the period | When available |63| GitHub activity | PRs and issues for the period (via the `github` skill) | Optional enrichment |6465Treat the session log as the system of record for what happened. Git history and GitHub66activity are derived evidence that corroborate or extend it. When a source is unavailable,67degrade gracefully: produce the artifact from the evidence you have and mark the missing68sections, never substitute invented data.6970A session log or transcript you will read on more than one turn, or one too large to71read whole, costs its full size on every turn that carries it. Distill it once with72`distill_artifact.py` (usage: context-optimizer skill, Tool Details: Distill73Artifact) and use the digest to locate evidence. When it lacks a detail, search the74raw source for that detail and read the matching lines with their context.7576---7778## Process7980The workflow is six sequential phases. Phase 0 gathers facts. Phases 1 and 2 interpret them.81Phase 3 decides actions. Phase 4 extracts and scores learnings. Phase 5 persists them. Each82phase links to the rubric and template it uses. Run them in order; do not interpret before83you observe.8485### Phase 0: Data Gathering8687Gather facts before interpretation. Observation precedes diagnosis.8889- Run the **4-Step Debrief** (Observe, Respond, Analyze, Apply): see90 [frameworks.md, 4-Step Debrief](references/frameworks.md#activity-4-step-debrief).91- Build the **Execution Trace** chronology: see92 [frameworks.md, Execution Trace Analysis](references/frameworks.md#activity-execution-trace-analysis).93- Run **Outcome Classification** (Mad, Sad, Glad): see94 [frameworks.md, Outcome Classification](references/frameworks.md#activity-outcome-classification).9596Evidence sources: the most recent session log under `.project-toolkit/sessions/`, `git log` for the97period, and optional GitHub activity through the `github` skill. Do not use raw `gh`.9899### Phase 1: Generate Insights100101Make meaning from data. Look past symptoms to find causes.102103- **Five Whys** is mandatory for every failure: see104 [frameworks.md, Five Whys](references/frameworks.md#activity-five-whys).105- **Fishbone Analysis** for complex failures with multiple contributing factors: see106 [frameworks.md, Fishbone Analysis](references/frameworks.md#activity-fishbone-analysis).107- **Force Field Analysis** when a pattern recurs despite knowing better: see108 [frameworks.md, Force Field Analysis](references/frameworks.md#activity-force-field-analysis).109- **Patterns and Shifts** for multi-session trends: see110 [frameworks.md, Patterns and Shifts](references/frameworks.md#activity-patterns-and-shifts).111- **Learning Matrix** for quick categorization when short on time: see112 [frameworks.md, Learning Matrix](references/frameworks.md#activity-learning-matrix).113114### Phase 2: Diagnosis115116Prioritize findings for action. Diagnostic priority order: critical error patterns, success117analysis, near misses, efficiency opportunities, skill gaps, traceability health. The full118priority order, traceability metrics, and diagnosis template live in119[diagnosis-and-actions.md, Diagnosis](references/diagnosis-and-actions.md#diagnosis).120121For each root cause that Five Whys surfaces, store a root-cause pattern for future122prevention: see123[diagnosis-and-actions.md, Root Cause Pattern Management](references/diagnosis-and-actions.md#root-cause-pattern-management).124125If the work touched diagnosis or action classification, stop here for the `diagnose this126failure` trigger; otherwise continue to Phase 3.127128### Phase 3: Decide What to Do129130Move from insights to action.131132- **Action Classification** (Keep, Drop, Add, Modify): see133 [diagnosis-and-actions.md, Action Classification](references/diagnosis-and-actions.md#activity-action-classification).134- **SMART Validation** of every proposed learning before storage: see135 [diagnosis-and-actions.md, SMART Validation](references/diagnosis-and-actions.md#activity-smart-validation).136- **Dependency Ordering** of the resulting actions: see137 [diagnosis-and-actions.md, Dependency Ordering](references/diagnosis-and-actions.md#dependency-ordering).138139### Phase 4: Learning Extraction140141Transform insights into stored knowledge. Score every learning 0 to 100 percent for142atomicity and reject vague statements. The scoring rubric, quality thresholds, worked143examples, and evidence-based tagging live in144[diagnosis-and-actions.md, Atomicity Scoring](references/diagnosis-and-actions.md#atomicity-scoring).145146Assemble the artifact using the byte-exact147[Learning Extraction Template](references/learning-template.md). Save to148`.project-toolkit/retrospective/YYYY-MM-DD-[scope].md`. When filling an auto-retro skeleton, overwrite149the placeholder sections in the existing `YYYY-MM-DD-auto-retro.md` and remove the UNFILLED150banner.151152### Phase 5: Persist and Close153154Persist learnings to memory and evaluate the retrospective itself.155156- Persist learnings with atomicity at or above 70 percent to Serena memory (ADR-037). Search157 for existing patterns before creating new entries to avoid duplicates: see158 [diagnosis-and-actions.md, Memory Protocol](references/diagnosis-and-actions.md#memory-protocol).159- Close with **+/Delta**, **ROTI**, and **Helped, Hindered, Hypothesis**: see160 [frameworks.md, Closing Activities](references/frameworks.md#closing-activities).161- Record each actionable delta item in the artifact's `Findings for the owner` table, classed162 from the frozen completion contract: see163 [frameworks.md, Delta Triage](references/frameworks.md#activity-delta-triage). Do not file a164 GitHub issue or write a backlog memory file. The owner decides what becomes tracked work.165166---167168## Success Criteria169170Before the retrospective is complete, confirm:171172- [ ] One Markdown file exists at `.project-toolkit/retrospective/YYYY-MM-DD-[scope].md` (or the173 existing auto-retro skeleton was filled and its UNFILLED banner removed).174- [ ] The artifact structure matches the175 [Learning Extraction Template](references/learning-template.md) byte-for-byte, with176 placeholders filled.177- [ ] Every extracted learning carries an atomicity score and an evidence reference.178- [ ] Learnings at or above 70 percent atomicity are persisted to Serena memory, or the179 memory write failure is noted in the artifact.180181---182183## Boundaries184185- This skill reads evidence and writes one artifact plus memory entries. It does not open PRs186 or file issues; it lists delta items for the owner in the artifact.187- Memory and GitHub are integration points. A failed memory call degrades to a documented188 fallback (write the artifact, note the memory write failed), never a silent context loss.189- Keep entry points thin. The Stop hook and `/retro fill` parse inputs and call this skill;190 they do not re-implement the workflow.191192---193194## Scripts195196| Script | Purpose | Exit codes |197|---|---|---|198| `scripts/run_retrospective.py` | Orchestrate Phase 0 to Phase 5 and write the retrospective artifact. | `0` artifact written; `1` a supplied learning scored below the persistence threshold (still written); `2` usage or configuration error; `3` unexpected external failure. |199| `scripts/extract_evidence.py` | Gather Phase 0 evidence (session log, git history) for the scope. | `0` evidence gathered (sources may be marked absent); `2` usage or configuration error; `3` unexpected external failure. |200| `scripts/score_atomicity.py` | Score a candidate learning against the 70% persistence threshold. | `0` at or above threshold; `1` below threshold (refine or reject); `2` usage or configuration error. |201202## References203204- [frameworks.md](references/frameworks.md): Phase 0, 1, and closing activity rubrics205 (4-Step Debrief, Execution Trace, Outcome Classification, Five Whys, Fishbone, Force Field,206 Patterns and Shifts, Learning Matrix, +/Delta, ROTI, Helped/Hindered/Hypothesis).207- [diagnosis-and-actions.md](references/diagnosis-and-actions.md): Phase 2, 3, 4, and 5208 rubrics (diagnosis priority and traceability, root-cause patterns, action classification,209 SMART validation, atomicity scoring, evidence-based tagging, memory protocol).210- [learning-template.md](references/learning-template.md): the byte-exact Learning Extraction211 Template that the output artifact must match.212- [recursive-extraction.md](references/recursive-extraction.md): the agent's Phase 5 templates213 (candidate list, delegation request, termination rules, artifact block).214- [handoff-example.md](references/handoff-example.md): a filled example of the agent's215 structured handoff block.216- `.claude/agents/retrospective.md`: the agent that loads these references. The references217 are the canonical home of the rubrics; the agent keeps only the gates and load conditions.