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 replaces the former retrospective agent (.claude/agents/retrospective.md).
It is callable from Skill("retrospective") and from /retro fill <date> (Issue #2079).
The Stop hook that once invoked it automatically was deleted in #3349, 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? |
| Session ended with meaningful work and you want learnings persisted |
Yes |
An unfilled auto-retro skeleton exists in .agents/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
.agents/retrospective/YYYY-MM-DD-[scope].md. When filling an auto-retro skeleton, write
to the existing YYYY-MM-DD-auto-retro.md file produced by the Stop hook.
Inputs
| Input |
Source |
Required |
| Scope |
User argument (session, task, date, PR) |
Yes |
| Session log |
.agents/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.
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 .agents/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
.agents/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.
- Route any P0 or P1 delta item to a GitHub issue through the
github skill; store P2 and P3
items in backlog memory.
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
itself; it routes delta items to the
github skill.
- 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.
.claude/agents/retrospective.md: the source agent body these references were lifted from
(canonical source for the rubrics; retired once the skill ships).
1---2name: retrospective3version: 0.1.04description: 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).5license: MIT6metadata:7 source: https://skillmd.com/skills/rjmurillo/retrospective8 domains: [retrospective, learning-extraction, root-cause-analysis, continuous-improvement]9 type: workflow10 inputs: [scope-description, session-log, git-history]11 outputs: [retrospective-markdown-file]12 adr: ADR-008, ADR-017, ADR-03713---1415# Retrospective1617<!-- vendor-portability: declared. This skill reads the consumer's most recent session log under .agents/sessions/ as evidence and writes the retrospective artifact to .agents/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 .agents/ gathers from git history alone and creates the output directory. Issue #2050. -->1819Turn execution experience into institutional knowledge. This skill orchestrates a fixed20Phase 0 through Phase 5 workflow that gathers evidence, generates insights, diagnoses root21causes, decides actions, scores atomicity, and persists learnings. The long-form rubrics22live verbatim in `references/`; this file is the orchestration contract.2324This skill replaces the former `retrospective` agent (`.claude/agents/retrospective.md`).25It is callable from `Skill("retrospective")` and from `/retro fill <date>` (Issue #2079).26The Stop hook that once invoked it automatically was deleted in #3349, so a27retrospective is written when someone asks for one.2829## Triggers3031| Trigger Phrase | Operation |32|----------------|-----------|33| `run a retrospective` | Full Phase 0..5 workflow over the given scope |34| `retro fill` | Fill an unfilled auto-retro skeleton for a date |35| `extract learnings from this session` | Phase 0..4 over the current session |36| `diagnose this failure` | Phase 0..2 root-cause analysis, then stop |37| `what did we learn` | Phase 4 atomicity-scored learning extraction |3839---4041## When to Use4243| Situation | Use This Skill? |44|-----------|-----------------|45| Session ended with meaningful work and you want learnings persisted | Yes |46| An unfilled auto-retro skeleton exists in `.agents/retrospective/` | Yes (fill it) |47| Diagnosing why a task failed (Five Whys, fishbone) | Yes |48| Capturing a single in-conversation correction ("no", "wrong") | No, use `reflect` |49| Saving a quick checkpoint with no analysis | No, use `/checkpoint` |5051The output artifact is a Markdown file. The Learning Extraction Template in52`references/learning-template.md` defines the exact structure. Save to53`.agents/retrospective/YYYY-MM-DD-[scope].md`. When filling an auto-retro skeleton, write54to the existing `YYYY-MM-DD-auto-retro.md` file produced by the Stop hook.5556---5758## Inputs5960| Input | Source | Required |61|-------|--------|----------|62| Scope | User argument (session, task, date, PR) | Yes |63| Session log | `.agents/sessions/` most recent for the period | When available |64| Git history | `git log` over the period | When available |65| GitHub activity | PRs and issues for the period (via the `github` skill) | Optional enrichment |6667Treat the session log as the system of record for what happened. Git history and GitHub68activity are derived evidence that corroborate or extend it. When a source is unavailable,69degrade gracefully: produce the artifact from the evidence you have and mark the missing70sections, never substitute invented data.7172---7374## Process7576The workflow is six sequential phases. Phase 0 gathers facts. Phases 1 and 2 interpret them.77Phase 3 decides actions. Phase 4 extracts and scores learnings. Phase 5 persists them. Each78phase links to the rubric and template it uses. Run them in order; do not interpret before79you observe.8081### Phase 0: Data Gathering8283Gather facts before interpretation. Observation precedes diagnosis.8485- Run the **4-Step Debrief** (Observe, Respond, Analyze, Apply): see86 [frameworks.md, 4-Step Debrief](references/frameworks.md#activity-4-step-debrief).87- Build the **Execution Trace** chronology: see88 [frameworks.md, Execution Trace Analysis](references/frameworks.md#activity-execution-trace-analysis).89- Run **Outcome Classification** (Mad, Sad, Glad): see90 [frameworks.md, Outcome Classification](references/frameworks.md#activity-outcome-classification).9192Evidence sources: the most recent session log under `.agents/sessions/`, `git log` for the93period, and optional GitHub activity through the `github` skill. Do not use raw `gh`.9495### Phase 1: Generate Insights9697Make meaning from data. Look past symptoms to find causes.9899- **Five Whys** is mandatory for every failure: see100 [frameworks.md, Five Whys](references/frameworks.md#activity-five-whys).101- **Fishbone Analysis** for complex failures with multiple contributing factors: see102 [frameworks.md, Fishbone Analysis](references/frameworks.md#activity-fishbone-analysis).103- **Force Field Analysis** when a pattern recurs despite knowing better: see104 [frameworks.md, Force Field Analysis](references/frameworks.md#activity-force-field-analysis).105- **Patterns and Shifts** for multi-session trends: see106 [frameworks.md, Patterns and Shifts](references/frameworks.md#activity-patterns-and-shifts).107- **Learning Matrix** for quick categorization when short on time: see108 [frameworks.md, Learning Matrix](references/frameworks.md#activity-learning-matrix).109110### Phase 2: Diagnosis111112Prioritize findings for action. Diagnostic priority order: critical error patterns, success113analysis, near misses, efficiency opportunities, skill gaps, traceability health. The full114priority order, traceability metrics, and diagnosis template live in115[diagnosis-and-actions.md, Diagnosis](references/diagnosis-and-actions.md#diagnosis).116117For each root cause that Five Whys surfaces, store a root-cause pattern for future118prevention: see119[diagnosis-and-actions.md, Root Cause Pattern Management](references/diagnosis-and-actions.md#root-cause-pattern-management).120121If the work touched diagnosis or action classification, stop here for the `diagnose this122failure` trigger; otherwise continue to Phase 3.123124### Phase 3: Decide What to Do125126Move from insights to action.127128- **Action Classification** (Keep, Drop, Add, Modify): see129 [diagnosis-and-actions.md, Action Classification](references/diagnosis-and-actions.md#activity-action-classification).130- **SMART Validation** of every proposed learning before storage: see131 [diagnosis-and-actions.md, SMART Validation](references/diagnosis-and-actions.md#activity-smart-validation).132- **Dependency Ordering** of the resulting actions: see133 [diagnosis-and-actions.md, Dependency Ordering](references/diagnosis-and-actions.md#dependency-ordering).134135### Phase 4: Learning Extraction136137Transform insights into stored knowledge. Score every learning 0 to 100 percent for138atomicity and reject vague statements. The scoring rubric, quality thresholds, worked139examples, and evidence-based tagging live in140[diagnosis-and-actions.md, Atomicity Scoring](references/diagnosis-and-actions.md#atomicity-scoring).141142Assemble the artifact using the byte-exact143[Learning Extraction Template](references/learning-template.md). Save to144`.agents/retrospective/YYYY-MM-DD-[scope].md`. When filling an auto-retro skeleton, overwrite145the placeholder sections in the existing `YYYY-MM-DD-auto-retro.md` and remove the UNFILLED146banner.147148### Phase 5: Persist and Close149150Persist learnings to memory and evaluate the retrospective itself.151152- Persist learnings with atomicity at or above 70 percent to Serena memory (ADR-037). Search153 for existing patterns before creating new entries to avoid duplicates: see154 [diagnosis-and-actions.md, Memory Protocol](references/diagnosis-and-actions.md#memory-protocol).155- Close with **+/Delta**, **ROTI**, and **Helped, Hindered, Hypothesis**: see156 [frameworks.md, Closing Activities](references/frameworks.md#closing-activities).157- Route any P0 or P1 delta item to a GitHub issue through the `github` skill; store P2 and P3158 items in backlog memory.159160---161162## Success Criteria163164Before the retrospective is complete, confirm:165166- [ ] One Markdown file exists at `.agents/retrospective/YYYY-MM-DD-[scope].md` (or the167 existing auto-retro skeleton was filled and its UNFILLED banner removed).168- [ ] The artifact structure matches the169 [Learning Extraction Template](references/learning-template.md) byte-for-byte, with170 placeholders filled.171- [ ] Every extracted learning carries an atomicity score and an evidence reference.172- [ ] Learnings at or above 70 percent atomicity are persisted to Serena memory, or the173 memory write failure is noted in the artifact.174175---176177## Boundaries178179- This skill reads evidence and writes one artifact plus memory entries. It does not open PRs180 itself; it routes delta items to the `github` skill.181- Memory and GitHub are integration points. A failed memory call degrades to a documented182 fallback (write the artifact, note the memory write failed), never a silent context loss.183- Keep entry points thin. The Stop hook and `/retro fill` parse inputs and call this skill;184 they do not re-implement the workflow.185186---187188## Scripts189190| Script | Purpose | Exit codes |191|---|---|---|192| `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. |193| `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. |194| `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. |195196## References197198- [frameworks.md](references/frameworks.md): Phase 0, 1, and closing activity rubrics199 (4-Step Debrief, Execution Trace, Outcome Classification, Five Whys, Fishbone, Force Field,200 Patterns and Shifts, Learning Matrix, +/Delta, ROTI, Helped/Hindered/Hypothesis).201- [diagnosis-and-actions.md](references/diagnosis-and-actions.md): Phase 2, 3, 4, and 5202 rubrics (diagnosis priority and traceability, root-cause patterns, action classification,203 SMART validation, atomicity scoring, evidence-based tagging, memory protocol).204- [learning-template.md](references/learning-template.md): the byte-exact Learning Extraction205 Template that the output artifact must match.206- `.claude/agents/retrospective.md`: the source agent body these references were lifted from207 (canonical source for the rubrics; retired once the skill ships).