# Retro

> Generate an actionable retro from Pi session logs + orchestration artifacts, and propose concrete doc/template improvements.

- Skill: `l3wi/retro` (Agent Skill)
- Install (CLI): `npx skillmds@latest add l3wi/retro`
- Raw SKILL.md: https://api.skillmd.com/api/skills/l3wi/retro/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: l3wi (https://skillmd.com/u/l3wi)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/l3wi/retro

---


# Retro Skill

Turn recent workflow execution into improvements.

Use this skill when the user asks for a retro, postmortem, workflow improvement, or wants to learn from agent mistakes.

## Outputs

Write:
- `docs/retros/{feature}/{timestamp}.md`
- `docs/retros/{feature}/{timestamp}-actions.md`

## Inputs

- Pi session logs (JSONL): `~/.pi/agent/sessions/.../*.jsonl`
- `.orchestration-state.json`
- `.orchestration-logs/**/events.jsonl`, `stderr.log`, `validation.phase.json`, `scope.json`
- `docs/specs/{feature}-spec.md`, `docs/plans/{feature}.md`, `docs/tasks/{feature}-phase-*.md`

## Procedure

### 1) Identify feature + timeframe

- Prefer feature name from `.orchestration-state.json.feature`.
- If not available, ask the user for `{feature}`.
- Choose a timestamp label:
  - `YYYY-MM-DDTHH-mm-ssZ`

### 2) Locate the relevant Pi session log

Pi sessions are stored as JSONL under:
- `~/.pi/agent/sessions/<cwd-sanitized>/...jsonl`

Find the correct session log:

```bash
# list the most recent sessions for this project
ls -t ~/.pi/agent/sessions/* | head

# narrow to this cwd by searching for the cwd header line
rg -n --fixed-string '"cwd":"' ~/.pi/agent/sessions -S | head
```

Pick the most recent JSONL file whose first line contains:
- `"type":"session"` and your project `cwd`.

### 3) Extract failure signals from the session

From the JSONL, extract:
- tool failures (`tool_execution_end` with `isError=true`)
- repeated retries / auto_retry
- merge failures
- validation failures

Examples:

```bash
# show tool errors
jq -rc 'select(.type=="tool_execution_end" and .isError==true)' session.jsonl | tail -n 50

# show assistant final messages
jq -rc 'select(.type=="message_end" and .message.role=="assistant") | .message.content' session.jsonl | tail -n 20
```

### 4) Correlate with orchestration artifacts

Read `.orchestration-state.json` and list:
- branches
- worktree paths
- run log dirs
- validation report paths

Then inspect:
- `events.jsonl` for each phase run
- `validation.phase.json` and `scope.json`

### 5) Write the retro

#### `docs/retros/{feature}/{timestamp}.md`
Must include:
- Summary (2-5 bullets)
- Timeline
- What went well / what went wrong
- Top 3 failure modes

#### `docs/retros/{feature}/{timestamp}-actions.md`
Must include:
- Doc drift fixes (exact file + exact change)
- Template fixes (task/spec templates)
- Automation gaps (what to gate next)
- Clear prioritization (P0/P1/P2)

### 6) Optional: spawn a session-review agent

If the retro is complex, spawn:
- agent: `session-reviewer`
- branch: `chore/{feature}-retro`

And have it write the two retro outputs.

## Guardrails

- Do not auto-apply doc changes without user confirmation.
- Do not require a daemon (Level 3). Keep recommendations in-process.