Retrospective: Where the Findings Actually Go

Agile teams hold retrospectives to look at what went well and what hurt, while it's still fresh enough to fix. I wanted the same for my work with Claude, so both of us learn from accumulated experience, beyond the last session. The retrospective skill keeps a journal of decisions, scores each one against what was expected, and ties every finding to evidence.

In this post

1. 01What the skill does
2. 02Why not just critique or handoff
3. 03Inside the folder
4. 04How it connects to the rest of the ecosystem
5. 05A real example
6. 06When a retro never gets filed
7. 07A silent fault in the capture path
8. 08Design decisions
9. 09Best practices
10. 10Limits
11. 11Next

flowchart TB
    D["Decision +<br/>expected outcome"] --> O["Observed result<br/>+ evidence"]
    O --> V["Verdict against<br/>the expectation"]
    V --> A["Owned action<br/>with a due date"]
    A --> R["Next retro:<br/>done, carried or dropped"]
      

What's not obvious: the last step closes the loop. An action nobody did comes back by name, and carrying or dropping it needs a reason.

What the skill does

A good decision can have a bad outcome, and a weak one can get lucky. A later review can tell them apart only if the expectation was written down at the time, the way a pre-registered study fixes its hypothesis before the data arrives.

This skill uses a hook to turn raw activity, decisions made, results observed and friction hit into structured journal lines tagged DECISION, EVENT, RESULT, FRICTION, WIN. Re-examining past events no longer relies on shaky memory after the fact or on the tedious pressure to multitask between doing the work and documenting it.

The journal is an append-only JSONL file. Each line is one record with a timestamp, a type, the session and, for a decision, the expected outcome. It keeps only what a later review can act on, and it never guesses a decision from a transcript.

You can type lines by hand, or a Stop hook can pull them from the transcript with a regular expression and no model call. The hook fires at the end of every turn. It takes decisions only from your own text, and the other four types from either side, with a separate cap on the assistant's share. If a decision comes without an expected outcome, the hook asks you for one and never guesses.

Each retro answers four questions

These map to eight phases, R0 to R7, listed at the end. The retro grows with the number of journal lines since the last one, from two lenses on a single task to the full panel at a project's close.

Question 2 gives one number, the share of resolved decisions that turned out as expected. The skill calls it a calibration rate. Strictly, it's an expectation-match rate, and it says nothing about probability calibration.

Why not just critique or handoff

The project already has two other review skills that might appear very similar, but only on the surface. Critique remembers its own findings on one file but nothing of the project around it, and Handoff looks exactly one session ahead. Each can trigger a small, bounded version of Retrospective skill directly when their own signals cross a threshold such as a defect that survives two review cycles or a repeating pattern in handoff snapshots, but neither of them is built to track on its own.

Inside the folder

retrospective/
├── SKILL.md
├── README.md
├── references/
│   ├── panel.md
│   ├── lite.md
│   ├── formats.md
│   └── destinations.md
└── scripts/
    └── retro_capture.py

SKILL.md is the protocol and README.md the setup. The references cover the panel, the LITE test, the document template and where files go. The script is the Stop hook, and it logs every session where it found nothing, so a quiet hook and a broken one look different.

How it connects to the rest of the ecosystem

flowchart TB
    CR["critique"] -->|"same finding in 2+ runs"| LT["LITE retro"]
    HO["handoff"] -->|"PATTERN not empty"| LT
    LT --> J[("journal")]
    CR -->|"review log"| R1["R1 Facts"]
    HO -->|"snapshots"| R1
    CR -->|"cost counters"| FL["finance lens"]
    J -->|"recurring friction"| HO
      

Every link here is optional.

• Critique or handoff can start a small LITE retro. It runs only if its own test finds two signals, writes at most 12 journal lines and one action, and skips the panel.
• The finance lens uses cost data, such as critique's counters or the time between journal entries. With neither, it reports nothing.
• Close-session runs retrospective, critique and handoff in sequence at the end of a working session.

A real example

This one comes from another project of mine, a solo pipeline that collects listings on a schedule and publishes a small dataset.

That week's journal was empty on purpose. The project keeps its record in an action ledger and daily notes, so the invocation named those as the sources.

One decision, traced

Two earlier actions that paid off

ROTI is the retro's score for its own usefulness, from 1 to 5. This one named its weakest part as a five-lens panel against a cap of four. The quotes are word for word, with names, paths, commit hashes and dates removed from the whole document.

See every table this retro produced →

When a retro never gets filed

A retro ends with two writes, the document and a closing marker in the journal. The next retro reads the marker to know where its period starts.

In the blog project behind this series, both writes failed:

1. The session couldn't write to the skill's state folder.
2. One retro ended up as a project document, with a copy in a stray folder.
3. The other sat for two days beside a script meant to file it, and nobody ran the script.
4. With no marker, the next retro would have counted zero new lines.

What changed since:

• Lines that can't land go to a prepared/ folder marked "staged, not landed".
• The stray-folder rule lives in project memory.
• The actions file has existed since 15 September.

• Still open: a proposal to apply R0's rule for ignored actions to open questions as well, after one question went through three retros unanswered.

A silent fault in the capture path

While I was writing this post, a critique run found two faults that failed silently.

Hook v2.5 and protocol v1.8 fix both. The hook now deduplicates by marker type and text within a session, and reads the last turn from the hook input, since the transcript file can lag.

The lesson: a capture path needs its own health signal, so a quiet week and a dead hook leave different traces.

Design decisions

Best practices

• Check that capture works. Read the hook's error log now and then. Where the hook can't run, as in this project's Cowork sessions, every journal line so far was typed by hand.
• Give each action a file or a command. By 12 September, the blog project had finished 1 of 12 tracked items, and every action in its last three retros was a habit for a future session.
• Put fixes where they load automatically. A fix buried in a retro document needs someone to reread it. In another project, a self-monitoring rule failed twice and was replaced by a check stated in the same turn as the action.

Limits

• An anchor shows traceability, and validity needs its own check. The example retro found a rollout where "every earlier claim about it had been citing other claims about it". A chain of citations is only as strong as its first primary source. A missing log is weaker still, since it can mean nothing happened or that the collector failed.
• Some surfaces can't run the hook or write skill state. Lines staged in prepared/ stay outside the journal, so the next retro has to be pointed at them.
• ROTI is self-reported. Nothing acts on a low score yet, and the open-questions rule hasn't shipped.

Next

The finance lens reports nothing when nothing measures cost. The next post covers the skill that does.

DECISION: <text> | expect: <expected outcome>   (expect required)
EVENT: <text>
RESULT: <text>
FRICTION: <text>
WIN: <text>

{"ts":"<iso8601 utc>","slug":"<slug>","type":"decision|event|result|friction|win","txt":"<one line, 300 chars max>","expect":"<expected outcome, decisions only, else null>","links":["<path or url>"],"sid":"<session id>","src":"hook|hook-assistant|manual|lite"}

{"id":"A<n>","ts":"<iso8601>","retro":"<retro filename>","horizon":"S|M|L","action":"<imperative, one line>","owner":"<person or target; defaults to the user>","target":"skill:<name>|config:<file>|project:<slug>|habit","due":"<yyyy-mm-dd>","status":"open|done|dropped|superseded"}