Ticket Retro

---
name: ticket-retro
description:
  "Cross-ticket retrospective VIEW (CTL-789 Loop C / CTL-814). **ALWAYS use when** a ticket's PR
  has merged and merge-pr's post-merge deploy-verification (CTL-2232) has resolved a terminal
  sentinel for it (the workflow's compound closing step — relay-native trigger, CTL-2244; see
  the `compound-estimate` skill's `references/trigger.md`), or when the user says 'ticket retro', 'run a
  retro', 'retrospective', 'what did we learn lately',
  or 'how are the estimates calibrating'. Synthesizes everything the compound loops captured since
  the last retro — friction logs, learnings, compound-log calibration, catalyst.db / merged-PR
  actuals — into thoughts/shared/retros/ticket/<date>.md with a persisted watch-items block, and
  surfaces top patterns in the morning briefing's Plan today."
allowed-tools: Bash, Read, Write, Grep, Glob
---

# Ticket Retro — the cross-ticket compound view

Loop C of compound engineering: a human-readable reflection across a SET of tickets. It mostly **reads** what Loop B (friction logs, learnings) and Loop A (compound-log, estimation corpus) captured, then writes ONE artifact: the retro document.

**Runs automatically per ticket, relay-native (CTL-2244):** `merge-pr` Step 14 (the `merge-pr` skill's `references/post-merge.md`) invokes this skill last — after `compound-estimate` and `ticket-compound` — once Step 13b's deploy verification (the `merge-pr` skill's `references/post-merge-deploy-verify.md`, CTL-2232) resolves a terminal sentinel for the merge, so the system learns from every ticket it ships without being asked, and this ticket's own learning (just written by `ticket-compound`) is already in the store by the time this runs — see the `compound-estimate` skill's `references/trigger.md` for the shared trigger contract and why this no longer depends on the retiring daemon-era `phase-monitor-merge` phase agent. Best-effort in that context — a retro failure never blocks a merge. Several merges per day are normal: same-day re-runs REGENERATE today's file cumulatively (the gather floor skips today — see Step 3).

**Hard contract — read-only VIEW:**

- The ONLY thing this skill writes is `thoughts/shared/retros/ticket/<YYYY-MM-DD>.md`.
- It must NOT curate the learnings store, edit `thoughts/shared/CONCEPTS.md`, or touch ADRs —
  that is `ticket-compound`'s job (per-ticket curator). No Linear writes, no corpus writes.
- Every input store degrades to `_none_` — empty stores are the normal early state, never an error.

**Paths.** Commands below name files inside this skill's own directory as `${CLAUDE_SKILL_DIR}/…`. Claude Code fills that in. On any other harness, set CLAUDE_SKILL_DIR to the absolute directory that contains this SKILL.md before running them. If you cannot, stop and report `skill_dir_unresolved`.

## Invocation

```
/catalyst-dev:ticket-retro                      # since-last-retro (default scope)
/catalyst-dev:ticket-retro --since 2026-06-01   # explicit window floor
/catalyst-dev:ticket-retro --tickets CTL-1,CTL-2  # explicit ticket set (all time)
```

Default scope is **since-last-retro, no time box** (solo-dev rhythm — design decision, plan
line 114): the window floor is the date of the most recent retro in
`thoughts/shared/retros/ticket/`; the first retro ever falls back to 14 days.

## Step 1: Gather (deterministic, read-only)

All reads go through the gather helper — one JSON document, every section degrades to empty:

```bash
GATHER="${CLAUDE_SKILL_DIR}/scripts/ticket-retro/gather-retro.sh"
RETRO_JSON=$(mktemp)
bash "$GATHER" --thoughts-dir thoughts "$@" > "$RETRO_JSON"
jq '{window, prior_retro: (.prior_retro != null), friction: (.friction|length),
     learnings: (.learnings|length), calibration: (.calibration.entries // 0),
     merged_prs: (.merged_prs|length), db_stats: (.db_stats|length)}' "$RETRO_JSON"
```

What it returns (see the script header for the full shape):

| Key | Source | Degrades to |
|---|---|---|
| `window` | latest `retros/YYYY-MM-DD.md` / `--since` / `--tickets` | 14-day default |
| `prior_retro.watch_items` | the previous retro's fenced `yaml watch-items` block | `null` |
| `friction[]` | `thoughts/shared/friction/*.md` (`## <phase> · <TICKET> · <ISO-8601>` records after the floor) | `[]` |
| `learnings[]` | `thoughts/shared/learnings/**` frontmatter, mtime after the floor | `[]` |
| `calibration` | `compound-log.sh aggregate` (estimate_at_start vs estimate_actual) | `{}` |
| `merged_prs[]` | `gh pr list --state merged` in-window, ticket id from branch/title | `[]` |
| `db_stats[]` | `~/catalyst/catalyst.db` sessions⋈session_metrics per ticket (SPARSE — see note) | `[]` |

**Actuals note:** `db_stats` covers only orchestrator-run tickets with metrics rows (historically ~13 of 333). `merged_prs[].additions/deletions` (diff churn) is the universal actuals fallback — use it for the aggregate stats; treat db cost/hours as a bonus column where present.

## Step 2: Synthesize (your judgment — this is the LLM half)

1. **What we did** — group `merged_prs` by ticket; one line each. Failed/abandoned tickets that
   show up in friction but not in `merged_prs` belong here too (often highest-signal).
2. **Recurring friction patterns** — cluster `friction[].line` entries that describe the same
   underlying problem (same component, same failure shape — NOT necessarily same wording). A pattern needs **≥2 records** (across tickets or phases). One-off frictions are listed only if severe. For each pattern: a name, the supporting records (`ticket·phase`), and one sentence of synthesis.
3. **Watch-item recurrence** — for each `prior_retro.watch_items[]` pattern, check whether this
   window's friction/learnings show it again. Verdict per item: `recurred` (cite evidence), `quiet` (no sighting), or `resolved` (a learning/ADR/fix landed that addresses it — cite it).
4. **Estimation calibration** — from `calibration`: count/exact/mean-signed-delta/median-abs-delta plus a per-ticket start→actual table. When `calibration.entries == 0`, render `_none_` and note the sink fills once the post-merge deploy-verification signal resolves (see the `compound-estimate` skill's `references/trigger.md`).
5. **Next watch items** — carry forward unresolved prior items (keep their `first_seen`) and add
   new patterns from (2) worth tracking. Cap at ~7 — a watch list longer than that is a backlog, not a watch list.

## Step 3: Write the retro document

Path: `thoughts/shared/retros/ticket/<YYYY-MM-DD>.md` (today UTC). **If today's file already exists, OVERWRITE it** — the gather floor deliberately skips today's retro (CTL-831), so a same-day re-run covers the same since-prior-retro window plus whatever just merged; today's file is always the cumulative day view, never a near-empty increment. Template:

```markdown
---
date: <YYYY-MM-DD>
type: retro
generated_by: ticket-retro
window_since: <window.since>
window_source: <window.source>
tickets_shipped: <N>
---

# Ticket Retro — <YYYY-MM-DD>

Window: <window.since> → today (<window.source>)

## What we did

- `CTL-x` title — #PR (+adds/−dels)
- …                                      (_none_ when empty)

## Aggregate stats

| Metric | Value |
|---|---|
| Tickets shipped | N |
| Diff churn (LOC) | +A / −D |
| Sessions / cost / hours (catalyst.db, sparse) | N / $C / H |

## Recurring friction patterns

- **<pattern name>** (N records: CTL-a·research, CTL-b·implement) — one-sentence synthesis.
- …                                      (_none_ when empty)

## What we learned

- [component] title — `path`             (_none_ when empty)

## Estimation calibration

entries: N · exact: N · mean signed delta: +X.X · median |delta|: X

| Ticket | start | actual | Δ |
|---|---|---|---|
…                                        (_none_ when empty)

## Watch items from last retro

- ✅ resolved / 🔁 recurred / 💤 quiet — <pattern> (evidence)
…                                        (_no prior retro_ on the first run)

## Watch items

```yaml watch-items
- pattern: "<short greppable description>"
  component: <orchestrator|phase-agent|broker|monitor|cli|ci|worktree|linear|execution-core|estimation|website|plugins>
  first_seen: <YYYY-MM-DD of when it first appeared — preserve across retros>
  source: <TICKET the clearest record came from>
```
```

**The watch-items block is the only stateful contract.** The next retro and the morning briefing
both machine-parse it: keep the exact fence info string `yaml watch-items`, the exact four keys,
and `pattern` values double-quoted. `component` uses the learnings-store enum
(`ticket-compound/reference.md`).

## Step 4: Sync + report

```bash
humanlayer thoughts sync 2>/dev/null || true
echo "ticket-retro: wrote thoughts/shared/retros/ticket/$(date -u +%Y-%m-%d).md"
```

Report to the user: the retro path, top 3 recurring patterns, the calibration one-liner, and any recurred watch-items. The next morning briefing surfaces the watch-items automatically (`Plan today → Retro signals`).

## Relationship to the other compound skills

| Skill | Owns | Scope |
|---|---|---|
| `ticket-compound` | learnings / CONCEPTS / ADR proposals (writes) | one ticket |
| `compound-estimate` | estimation numbers → compound-log (writes) | one PR |
| **`ticket-retro`** | the cross-ticket VIEW (reads both, writes only its retro doc) | a window of tickets |