/retrospect

description: "Run a structured retrospective on a shipped commit range, release, deployment, PR, commit, or session. Per-fix validation enforcement, active evidence-sourcing pass (autonomous lookups + targeted user-asks for anything that could become objective), simpler-alternative discipline, re-diagnosis, action verdicts, and a growing failure-mode pattern library. Triggers: '/retrospect' (auto-range), '/retrospect commit <hash>', '/retrospect range <ref1>..<ref2>', '/retrospect pr <num>', '/retrospect session', '/retrospect release', '/retrospect deployment'. Backward-compat flags (--range, --pr, --session, --commit) still accepted. (Code port — ADR-094.)"

/retrospect — Release retrospective with validation enforcement

Run a structured retrospective on a shipped commit range (or single commit, or current session). Produces a 10-section markdown report with per-fix verdicts, validation status, action recommendations, and re-diagnosis when fixes failed. Writes findings to `knowledge/logs/retrospect/` and runs aria's standard intake. Source spec: `docs/specs/2026-05-03-retrospect-skill-design.md`.

When to use

• After a release ships and the bug is partially or fully unresolved
• When the user reports a regression and a recent change set could be the cause
• Before proposing another fix to a bug that's already been "fixed" once
• As a soft-suggested response to user pushback ("review what you did," "are these changes necessary")

Step 0: Inputs & Mode Detection

Parse the invocation arguments. The first positional argument is the **scope keyword**; subsequent positional arguments are scope-specific. Seven scopes plus a no-args default:

| Scope | Trigger | Backward-compat flag (still accepted) | Bundle source | |---|---|---|---| | **(no args)** | `/retrospect` | — | Auto-range: last push on current branch — `git log @{push}..HEAD` if upstream is set, else `git log -10` and ask user to confirm range | | **commit** | `/retrospect commit <hash>` | `--commit <hash>` | Single commit | | **range** | `/retrospect range <ref1>..<ref2>` | `--range <ref1>..<ref2>` | `git log <ref1>..<ref2>` | | **pr** | `/retrospect pr <num>` | `--pr <num>` | `gh pr view <num> --json commits` then resolve to commit SHAs | | **session** | `/retrospect session` | `--session` | Files Claude has touched in the current conversation (read from session state, not git). No deploy yet — all fixes auto-tag 🚫 unvalidatable. | | **release** (NEW) | `/retrospect release` | (none) | Commits since the most recent semver tag. `git describe --tags --abbrev=0` to find the tag, then `git log <tag>..HEAD`. If no tags exist on the repo, fall back to auto-range and warn the user. | | **deployment** (NEW) | `/retrospect deployment` | (none) | Commits since the last deployment marker — see "Deployment detection cascade" below. |

**Argument parsing rules:**

• If the first positional arg matches a scope keyword (case-insensitive), use it. Otherwise treat it as auto-range and try to parse the args under the legacy flag form.
• Backward-compat flag forms (`--range`, `--pr`, `--session`, `--commit`) remain accepted indefinitely. Both `/retrospect range a..b` and `/retrospect --range a..b` resolve identically.
• Modifier flags (apply to any scope): `--ticket-post` (post the retrospective verdict to detected tickets at end; legacy alias `--linear-post` still accepted), `--no-source` (skip Step 3.5's Evidence-Sourcing Pass), `--lens=overbuild` (run the over-build review pass — see "Over-build lens" section; opt-in, off by default).

Deployment detection cascade (Q2.1=3)

When invoked as `/retrospect deployment`, attempt to resolve the deployment marker by trying these signals in order. First success wins; on no-success, fall through to the prompt.

1. **GitHub Releases** — `gh release view --json publishedAt,tagName 2>/dev/null` (most recent release). If returned, treat the release tag as the marker; bundle = `git log <tag>..HEAD`. 2. **Semver tags** — `git tag --sort=-creatordate | head -1`. If a tag matches `v?\d+\.\d+\.\d+` (and step 1 returned nothing), use it as the marker. 3. **Last commit on `main` (or `master`)** — `git log -1 --format=%H origin/main` (or `origin/master` if `main` doesn't exist). Treat as the marker; bundle = `git log <sha>..HEAD`. This catches projects without releases or tags. 4. **Prompt user** — if none of the above resolved (e.g., no remote, no tags, no `gh` auth), ask: "I couldn't auto-detect the last deployment for `/retrospect deployment`. Provide a marker (commit hash, tag, or ISO timestamp), or type `auto-range` to fall back to last-push behavior."

Print the resolved marker source ("Detected via gh release: v1.4.2 (2026-05-01)") in the Anchor block (§4.1) so the user can verify what the skill thought "deployment" meant.

After mode detection, gather:

1. **Goal** — Ask the user: "What was this release/range supposed to fix? (One sentence is fine.)" If they don't reply, fall back to commit message subjects + PR description. 2. **Tickets** — Scan commit messages with regex `\b([A-Z]{2,}-\d+)\b` for ticket IDs (the pattern is vendor-neutral — it matches DEV-123, PROJ-45, JIRA-9 alike). If any are found AND a project-tracker MCP is available, fetch each ticket's Product/Technical Intake + recent comments. If a project-tracker MCP is unavailable, note "ticket context unavailable" but continue. 3. **Post-deploy outcome** — Ask the user: "For each fix, what's the post-ship evidence? (✅ closed / ⚠ partial / ❌ failed / ❓ untested)" Show the per-commit list and accept inline replies. If user can't supply evidence for any fix, mark those ❓ and note that §10 will recommend instrumentation.

If scope is `session` (or invoked via `--session`), skip post-deploy outcome (no production yet) and tag all fixes 🚫 unvalidatable; their actions will resolve to HOLD-PENDING-DEPLOY.

Step 0.5: Active Knowledge Surfacing

If the user's config (`~/.gemini/antigravity/aria-knowledge.local.md`) has `active_kno