retro

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

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:

# 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:

# 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.