---
name: sdlc-retro
description: The Retrospective / learning executor — after a goal ships, surface the structural + product debt the narrow fix left behind, check what shipped against the original intent, and route each durable lesson to the right store (audit trail / north-star / standing rule). Advisory — it proposes, and parks north-star + standing-rule changes for your approval. Use at the end of a goal, in the Retrospective phase, or when the user runs /sdlc-retro.
allowed-tools: Bash(python3 *), Bash(git *), Bash(gh issue *)
---

# sdlc-retro

The **Retrospective (Learn)** phase executor — LoopSmith's backward-learning loop, so a goal doesn't
just ship, it *teaches*. Runs at the end of a goal, **after Review**. Grade **intent-vs-shipped as an
independent, project-informed pass** — under `config.review.independent` (default on) the loop runs it
as a fresh subagent, so the honest "did we build what the goal asked, and what debt did the narrow fix
leave?" isn't answered by the same context that just argued the work was done. It is **advisory**: it
proposes, writes only the audit-trail note freely, and **parks** any north-star or standing-rule change
for your approval — it never rewrites your standing docs unattended (mirrors how `sdlc-kg`'s `maintain`
only proposes).

## Executor resolution (host-aware)
No `superpowers` / `code-review` companion covers retrospective learning, so this is **always
LoopSmith's own**. It *complements* the Review phase's `superpowers:verification-before-completion`
(which asks "is it correct / done?") — it does not duplicate it (this asks "what did we learn, what
debt remains?"). Pure markdown discipline + `git` / `python3`, so it degrades gracefully on any host.

## Pre-flight — gather the evidence (repo-auto-detect, fail-open)
Read what this specific repo offers; skip whatever's absent (never break the run):
- **The original intent** — the goal's own text: the `.sdlc/goals/NNNN-*.md` file (local mode) or the
  issue body (`gh issue view "$goal"`, github mode).
- **What shipped** — the diff for this goal's work (`git diff` / `git log` over its branch or commits).
- **The journey** — `.sdlc/journey/<goal>.md` (local) or the issue timeline (github): the phase notes
  and 🔒 Critical Insights recorded as the goal ran.
- **Standing context** — the repo `README`, `.sdlc/context/north-star.md` (if present),
  `.sdlc/project.md`, and any `CLAUDE.md` / `AGENTS.md` governing the paths the goal touched.

## 1. Structural reflection — the debt the narrow fix left behind
- **Multi-site smell** — did one logical fix touch 2+ places? That's a missing shared contract /
  abstraction; name it.
- **Coverage themes** — did review keep finding the same class of gap (e.g. "no test exercises the real
  path")? Propose the convention or helper that closes it.
- **Deferred roots** — for each thing the plan left out, classify: *tactical* defer (fine, leave it) vs
  *structural* defer (a missing primitive — promote to a recommendation).
- **Rule alignment** — did the work reinforce a standing rule (cite it), or reveal one worth adding or
  retiring?

## 2. Product reflection — the gaps the work revealed
- **Friction / quality signals** — where did the work feel like fighting the product? A UX or feature gap?
- **Bugs that are features** — did the goal want something the system had no place for? Name the missing
  capability.
- **Direction** — does this advance the north-star / strategy, or drift out of scope?
- **Negative space** — what should the run have produced but didn't?

## 3. Intent-vs-shipped + the three-store learning harvest
**Intent-vs-shipped** — compare what actually shipped (the diff) to the goal's original text. Grade it:
- **achieved** — the intent is realized;
- **partial** — realized for some of it; *name the residual gaps* and confirm each has a tracking item;
- **diverged** — what shipped differs from the intent; say how and why.

Record the grade as an event too (optional, `telemetry.enabled`):
`python3 "${CLAUDE_SKILL_DIR}/../sdlc-loop/scripts/loop.py" emit .sdlc "$goal" retro --grade achieved|partial|diverged`

**Route each durable lesson to the right store.** Most stop at the first; the rest are *proposed* and
*parked* for approval:
- **Audit trail** — rationale worth re-reading later → record it on the goal:
  `python3 "${CLAUDE_SKILL_DIR}/../sdlc-loop/scripts/loop.py" note .sdlc "<goal>" "retro: <lesson>"`
  (comments the issue in github mode, appends to `.sdlc/journey/` in local mode). Safe to write freely.
- **North-star** — if the build *taught the strategy or architecture* (a bet confirmed / refuted, the
  code's shape now differs from a rule) → **propose** an edit to `.sdlc/context/north-star.md` and let
  the user approve it. Don't auto-write.
- **Standing rule** — a lesson that must gate *every* future plan / review **and isn't mechanically
  enforced** (if a linter / type-checker / CI already catches it, a rule is redundant) → **propose** a
  numbered rule for `.sdlc/project.md` or the governing `CLAUDE.md`. Rare; always parked.
- **Registered invariant** — the rare standing rule that is *also* a value constraint on a named thing
  in known files (`timeout ≤ 30`, `verify_ssl == True`). Nothing else catches it, and prose won't stop
  it recurring — so propose an entry for `.sdlc/decisions.json` via **`/sdlc-decide`**, and the next
  edit that breaks it is refused rather than reviewed. Rarest of all: if you can't write it as a
  comparison, it's a standing rule, not an invariant.

Route by test: audit-trail = "worth re-reading"; north-star = "changes our direction or shape"; standing
rule = "must gate every change and nothing else enforces it". De-duplicate — a lesson seen across
multiple goals is higher-confidence and a stronger candidate for the north-star or a rule.

## 4. Standing-doc rot — what this goal made obsolete
Docs grow by addition and shrink by nobody. Adding a rule has an obvious moment; retiring one never
does, so this is that moment. Ask what the goal just made redundant, and **propose** each removal the
same way — parked for approval, never written unattended:

- **A rule now enforced mechanically.** If the work added a linter rule, a type constraint, a schema
  check, or a CI job that catches what a numbered rule describes in prose, the prose is redundant —
  propose demoting it. Verify the enforcement is real and covers the whole rule before proposing;
  a rule half-enforced still needs its prose.
- **A rule whose premise moved.** The goal changed the shape the rule was written against. Propose
  the correction, quoting the old line and the code that now contradicts it.
- **Superseded plans and roadmaps.** A plan under `.sdlc/plans/` whose work just shipped is finished
  history — propose archiving it. This matters mechanically as well as tidily: the hard plan-gate
  treats any *recent* file under `.sdlc/plans/` as a fresh plan, so stale plans left lying there
  weaken the gate.
- **Nothing rotted** is the common answer and a fine one. Say it in a line and move on — do not
  manufacture a demotion to look thorough.

Archive, never delete: move superseded files aside so git history stays readable, and leave anything
append-only (a decision log, the journey trail) untouched — those are dated records, not stale docs.

> The mechanical counterpart runs in `/sdlc-doctor`, which reports standing-doc references that no
> longer resolve. That one is a script and needs no approval; this one changes meaning, so it asks.

## Output
A short retro: the intent grade (achieved / partial / diverged) + residual gaps, the structural +
product findings, and a **proposals table** (lesson → store → the exact edit), with every standing-doc
change clearly marked **needs your approval**. Record the audit-trail notes as you go; hand the parked
proposals to the user. Additions and retirements share the one table — a proposed demotion (§4) is the
same kind of parked change as a proposed new rule, and listing them together is what keeps the standing
docs from only ever growing.

**Autonomous (`/sdlc-loop`) mode:** run the reflection and **write only the audit-trail notes**; write
the proposals into the journey and **park** every north-star / standing-rule change to the review queue
for a human — never edit a standing doc unattended. Fail-open: if `git` / `gh` / a file is missing, note
it and continue. Retro never breaks a run.