retro

name	retro
disable-model-invocation	true
description	Generate a retrospective document from the current AI coding session and publish it to the team retro repo.
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:

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

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

If no team is configured (no default_team and no teams in ~/.logbook/config.yaml), publish is a no-op opt-out: the CLI prints the staged source directory and exits cleanly. Report where the retro is staged and that no team is configured — this is the expected outcome for users who run logbook without a team repo, not a failure.

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

Step 7: Harvest the session's notes

This retro consumed the session's notes (the notes[] from logbook session), so mark them harvested with the id from that same output:

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/logbook" note harvest <session-id>

Harvesting moves the session's notes log to notes/harvested/ so its deferred notes stop surfacing as orphan reminders at the next session start. Run it whether or not a team was configured — the notes were consumed either way.

Step 8: Confirm

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