retro - SKILL.md Agent Skill

name: retro description: Generate a retrospective document from the current AI coding session and publish it to the team retro repo. Triggers on 'retro', 'retrospective', 'capture this session'. argument-hint: "[category]"

`/logbook:retro`

Generate a retrospective for the current session and publish it to the team retro repo configured via /logbook:logbook add-team.

The skill orchestrates user-facing decisions; deterministic operations defer to the logbook CLI. Run any CLI invocation as:

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/logbook" <subcommand> [args]

Pre-flight: CLI freshness check

Before running the steps below, compare logbook --version against the plugin version in ${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json. If they differ, surface a one-line note and offer /logbook:logbook install-cli to refresh the shell wrapper. If logbook isn't on PATH, skip silently.

Step 0: Identify the session

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/logbook" session

Returns JSON: id, name, slug, tool, model, start, end, tokens, transcript, a notes array (the observations captured this session via /logbook:note), plus a detailed block with tool usage, files touched, timeline, user messages, overlapping sessions, concurrency (overlapping, max_parallel, wall_hours), git activity, initial context tokens, compaction events.

Retro-worthiness signal

Read notes first. Its length is the signal for whether this session earned a retro: if the user flagged observations mid-session, that is the evidence. Surface the count — "this session has N captured notes" — when confirming the user wants to proceed. A session with zero notes and little activity may not warrant one; say so rather than generating a thin retro.

Step 1: Read the metrics

Note tool usage, files touched, git activity, token usage, and any overlapping sessions. The concurrency block already reports max_parallel (peak simultaneous sessions) and wall_hours — read them directly; do not recompute a sweep line. If overlap exists, ask the user whether any were intentionally concurrent and should be reflected in the retro.

For Claude Code, token usage is exact. For Cursor, token estimates are unreliable — they only capture visible message text and miss cache reads (which dominate actual usage by 50-100x). Note source and reliability when including token data.

Cost estimation

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/logbook" retro estimate-cost \
  <input_tokens> <output_tokens> <cache_create> <cache_read> --model <model>

Pass the full Anthropic model id from logbook session (e.g. claude-opus-4-7, claude-sonnet-4-6, claude-haiku-4-5). Pricing is sourced from the vendored LiteLLM table at scripts/model_prices.json — refresh with just refresh-prices if a recent model is unknown. Output format: ~$X.XX.

Step 2: Gather context

Show what was auto-detected and propose defaults:

Category: Suggest one based on session activity. Use $ARGUMENTS if provided.
Slug: Default to slug from logbook session output. This is the directory name for the retro.
Date / tool / model: Today and the tool/model from logbook session.
Session ID: Auto-filled from the session output — do not ask.
Device ID: Auto-filled from logbook device-id — do not ask.

Start from the captured notes. The notes array from Step 0 is pre-gathered retro material — each entry carries the observation text, its kind (friction / win), and the transcript_line where it was raised. Sort them into the sections below and confirm and expand each with the user rather than reconstructing the session cold: a win seeds What Worked Well, a friction seeds What Didn't Work or an Observation. The notes are what the user already flagged as mattering; lead with them.

Then ask the user to confirm or correct the defaults, and provide what the notes and metrics can't supply:

Deliverable links: PRs, MRs, repos, or other artifacts
Brief description: What was the task? What was the outcome?
The prompt used (if applicable): the working prompt that produced results
What worked well + why (not just "it worked") — seeded by win notes
What didn't work: specific things that went wrong or required iteration — seeded by friction notes
Observations: generalizable lessons and actionable takeaways — expanded from the notes

Step 3: Get the device id

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/logbook" device-id

Generates and persists ~/.logbook/device-id on first run. Subsequent runs return the same id.

Step 4: Read the template

TEMPLATE=$(python3 "${CLAUDE_PLUGIN_ROOT}/scripts/logbook" retro template-path)
cat "$TEMPLATE"

Use the template for structure and quality standards.

Step 5: Stage the retro locally

mkdir -p /tmp/logbook-staging/<slug>

Write index.md with frontmatter:

---
date: YYYY-MM-DD
category: <category>
slug: <slug>
session_id: <session uuid>
device_id: <device id>
cost: "~$X.XX"
tool: <tool>
model: <model>
initial_context: <token count>
---

Body follows the template. The published artifact is index.md only — do not stage anything else.

Step 6: Publish

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/logbook" retro publish <category> <slug> /tmp/logbook-staging/<slug>

This:

Reads the team's clone path from ~/.logbook/config.yaml.
Pulls latest from the remote (rebase).
Copies the staging contents to <clone>/retros/<category>/<slug>/.
Commits with message retro: <category>/<slug> and pushes.

If multiple teams are registered, pass --team <name> to override the default.

On rebase conflict or push failure, the CLI bails loudly and leaves the team clone in place for manual resolution.

Step 7: Confirm

Print the published path and the remote URL where the retro now lives.