Retro

---
name: retro
description: Trend review across many sessions - velocity vs planned dates, eval-score trend toward target, failure-category trends from journal triage and investigations, and a status check on every open PLAN risk. Reads JOURNAL/PLAN/eval history, writes a dated retro entry into JOURNAL.md. Use when the user asks for a retro, a weekly review, or a phase-end wrap-up.
argument-hint: "[week | phase N | notes]"
---

# /retro — the trend across sessions

/journal records one session; /retro reads many and says where the line
is heading. Not a summary — a trend, with the numbers that make "we're
slipping" or "the eval is climbing" a fact instead of a feeling.

`Adjacent skills:` /journal (one session's worklog; /retro trends across
many) · /audit eval (one report's honesty; /retro the trend across runs)
· /triage (grooms the backlog; /retro reviews the trajectory).

<!-- acstack:runtime -->
Run before the skill's steps — per invocation, not per session (4.36); failures degrade to markdown:
```bash
link="$(readlink "$HOME/.claude/skills/health" 2>/dev/null || true)"   # empty = not symlinked
pack="$(dirname "$(dirname "$link")")"   # NEVER trust this unless $link was non-empty
if [ "${link#/}" != "$link" ] && [ -x "$pack/bin/acstack-config" ] && ! "$pack/bin/acstack-config" runtime | grep -q '=off'; then
  "$pack/bin/acstack-config" || true          # resolved keys, with sources
  "$pack/bin/acstack-update-check" || true    # ≤1 fetch/day; silent ONLY if already checked today
  "$pack/bin/acstack-recall" || true          # LEARNINGS.md + bug-class names, capped 3KB
else
  echo "runtime off — proceeding without recall/update-check"
fi
```
<!-- /acstack:runtime -->

<!-- acstack:principles -->
## Operating principles

- Be direct. Push back in writing when the plan or the user is wrong. No sycophancy.
- Never delete a decision. Supersede it: `~~old~~ → **Verdict (YYYY-MM-DD):** new call — reason.`
- Never fix, tune, or delete a test or eval case to raise a score. Log the miss honestly and leave the case unchanged.
- Name exact things: regex patterns, function signatures, model names, before → after numbers. Never "fixed bugs".
- Attribution: follow the project's `attribution` setting (default `none`) — no AI-tool mentions in generated docs, no attribution trailers in commits or PRs. Commit with explicit `-m`/`-F` messages only.
- Config: read `.claude/acstack.md` at the project root (fall back to `~/.claude/acstack.md`) before acting. `## Settings` keys override pack defaults; a `## <skill-name>` section overrides both. Unknown keys and sections are ignored.
- Docs: BRIEF.md (frozen seed) / PLAN.md (living plan) / JOURNAL.md (rolling journal). If the repo uses legacy names (PLANNING_PROMPT.md / PLANNING.md / STATUS.md), use those instead — never create both.
- Recall: if `LEARNINGS.md` exists at the project root, read it before starting.
- Conduct: follow the `acstack-conduct` block in this repo's AGENTS.md — the word is the mode; the user sets the pace.
- Hackathon lane: if the project's AGENTS.md carries the `acstack:hackathon-lane` block, only `/do` changes the repository during the event. Any other skill that would write a tracked file, commit or push says what it would have done and stops; a change that is not a task goes through the lane's operator route.
<!-- /acstack:principles -->

**One document set.** Resolve exactly ONE BRIEF/PLAN/JOURNAL set and name
its path in the report's scope line. If more than one candidate set exists
— a monorepo, nested products, an `apps/*` tree each with its own docs —
list the candidates and STOP. Never pick one silently: a confident answer
about the wrong product is worse than no answer (conduct rule 8).

## Inputs

- JOURNAL.md entries since the last retro (the window; `week` or
  `phase N` in the argument narrows it).
- PLAN.md: planned phase dates, exit criteria, the open risks and items.
- Eval artifacts when present: `eval/spec.md` targets and the result
  files across runs.
- `git log` over the window for commit / checkbox velocity.

**Retrieve by window, don't ingest the file.** Past roughly 500 lines,
JOURNAL.md is read headings-first: scan the `###` entry headings and their
dates, select the ones inside the window (`week`, `phase N`, or since the
last retro), and fetch full text for those only. Entries outside the window
are not evidence for this retro — reading them wastes budget and, worse,
invites a trend claim drawn from data the window explicitly excluded. State
the window and how many entries fell inside it, so a reader can tell a
five-entry trend from a one-entry anecdote.

**Missing inputs are named, never worked around.** No JOURNAL.md → stop:
a retro is a trend across recorded sessions, and without the record there
is no trend, only the git log's shape — say that and point at `/journal`.
No PLAN.md → run the trends that only need the journal and state that
velocity-vs-plan and the risk review were skipped for want of the plan. A
window containing one entry is reported as one entry, not extrapolated
into a trend.

## Sections

The four sections live in `references/retro-sections.md` with their
question sets and honest-degradation lines. Lead with a verdict:
`on plan` / `slipping — <where>` / `off plan`.

1. **Velocity vs plan.** Planned phase dates vs actual; boxes or issues
   closed per period vs the plan's implied rate; slippage named in days
   with the cause pulled from journal entries, not guessed.
2. **Eval trend.** Headline score per run across the window, per-category
   direction, distance to target. No eval history → one honest line and
   the section ends.
3. **Failure-category trends.** Counts by class from the journal's eval
   triage sections and /investigate write-ups; a class recurring 2+
   times is named as a /learn promotion candidate.
4. **Risk review.** Each open PLAN risk: still real / materialized /
   retired, with evidence. New risks are proposed as dated PLAN edits —
   proposed, never applied by /retro.

## Not in wave 3

No skill-usage / telemetry section — it arrives with the local
telemetry it reads (PLAN task 4.3, moved to wave 4.5 post-launch by the
2026-07-29 split). Don't emit a placeholder for it; its absence is
correct, not a gap.

## Output

Append to JOURNAL.md as a dated entry under `## Key decisions and
journey`, newest first:
`### Retro (YYYY-MM-DD — <window>)`. **This is the same anchor `/journal`
writes at**, so a retro and a journal entry from two concurrent sessions
conflict — which is the safe outcome, and is resolved by keeping both
entries rather than choosing one (see `/journal` step 2). A journal without that heading —
hand-kept rather than seeded from /journal's template — takes the entry
per that journal's own convention: appended where its entries actually
go (top of a newest-first record, bottom of a chronological one), with
the divergence named inside the entry; never scaffold the pack's
skeleton into a journal the project keeps by hand, and never impose the
pack's ordering on it. Commit using the project's
`journal-commit-format` (pack default `Journal <date>: <summary>`) with
`retro — <summary>` as the summary, brief body, attribution per config.
PLAN edits the retro proposes are listed for the user to apply
via `/plan replan` — /retro writes the journal, not the plan.

## Tickets-mode delta

Velocity becomes closed issues + milestone burn via
`gh issue list --state closed` and the milestone API; failure classes
are additionally mined from issue labels and closing comments.
Preconditions — `gh` installed, `gh auth status` succeeding, and a
GitHub remote present. Any failure names WHICH one failed and offers
document mode; never guess.