aria-knowledge

/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.

Runtime Gate (per ADR-094)

Canonical resolution: This is the Claude Code variant. When both plugin-claude-code and plugin-claude-cowork are loaded in the same session (most common in Claude Desktop), bare /retrospect resolves to this skill — aria-knowledge (Code) is the canonical owner of all 24 dual-port skills per ADR-094 §Part 1. The Cowork variant is namespaced-only: /aria-cowork:retrospect.

Before Step 0: Check that the Bash tool is available in this session. If Bash is NOT available (you are running in Claude Cowork or another non-Code runtime), surface the following notification and wait for explicit user confirmation:

⚠️ Runtime mismatch — you invoked aria-knowledge's /retrospect from a non-Code runtime.

This variant runs git log, git diff, gh pr view directly via Bash for commit/range/pr/deployment scopes. For the Cowork-native variant (prompts user-paste for git output; session/decision scopes work unmodified), use /aria-cowork:retrospect.

Use /aria-cowork:retrospect instead? (y / n)

Wait for an explicit reply:

• y / yes — Use the Skill tool to invoke aria-cowork:retrospect with the same arguments the user provided to this invocation. Do not proceed with this skill's steps; the cowork variant takes over and runs to completion. This is the default-yes path — auto-redirect is the helpful action.
• n / no — Proceed with this (aria-knowledge) variant anyway despite the runtime mismatch. The user has explicitly opted in.
• No response / any other reply — Treat as "do not proceed" and exit cleanly without running either variant.

This gate applies even when mode = auto per ADR-094 §Part 3. Auto mode's "implicit-yes on all gates" rule is suspended for the runtime-mismatch check — auto trusts that the user invoked the correct variant, and this gate enforces that precondition. All other auto-mode gates remain bypassed. The friction cost is now low: on y, the auto-redirect runs the correct variant with the original args.

If Bash is available, proceed to Step 0.

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): --linear-post (post the retrospective verdict to detected Linear tickets at end), --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 Linear-style ticket IDs. If any are found AND Linear MCP is available, fetch each ticket's Product/Technical Intake + recent comments. If Linear 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 (~/.claude/aria-knowledge.local.md) has active_knowledge_surfacing: true (default as of v2.15.0), surface relevant tagged knowledge BEFORE Steps 1-3 so loaded files inform pattern selection and evidence sourcing. If the field is false, skip this step entirely (note Active surfacing: disabled in the Anchor block).

Algorithm:

1. Build query. Combine, separated by spaces: the Goal sentence from Step 0; the first 3 commit subjects in the bundle range; PR title if scope is pr; any detected Linear ticket IDs (e.g., LINEAR-123); the resolved deployment marker label if scope is deployment; the range descriptor (e.g., v0.4.2..HEAD).

1. Read the index. Read <knowledge_folder>/index.md (resolve <knowledge_folder> from the config's `kno