Help us improve
Share bugs, ideas, or general feedback.
From retro
Use at end of a Claude Code session, on-demand for specific issues, or periodically for cross-session audits, to detect friction patterns and materialize learnings into the correct destination (user memory, project rules, skill PRs, checkpoints, or harness artefacts). Triggers: /retro command, 'retrospective', 'review the session', 'fix this skill', 'we keep hitting this', 'audit the architecture'.
npx claudepluginhub netresearch/claude-code-marketplace --plugin retroHow this skill is triggered — by the user, by Claude, or both
Slash command
/retro:retroThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
This skill replaces continuous friction-detection hooks with a single efficient LLM pass over the session transcript. It detects friction, classifies into one of six destinations, and materializes approved learnings.
Guides Next.js Cache Components and Partial Prerendering (PPR): 'use cache' directives, cacheLife(), cacheTag(), revalidateTag() for caching, invalidation, static/dynamic optimization. Auto-activates on cacheComponents: true.
Migrates code, prompts, and API calls from Claude Sonnet 4.0/4.5 or Opus 4.1 to Opus 4.5, updating model strings on Anthropic, AWS, GCP, Azure platforms.
Breaks plans, specs, or PRDs into thin vertical-slice issues on the project issue tracker using tracer bullets. Useful for converting high-level work into grabbable implementation tickets.
Share bugs, ideas, or general feedback.
This skill replaces continuous friction-detection hooks with a single efficient LLM pass over the session transcript. It detects friction, classifies into one of six destinations, and materializes approved learnings.
Core principle: No silent writes. Every materialization requires explicit user approval per proposal.
/retro — SweepAnalyze the entire current session. Returns ≤10 actionable proposals grouped by destination. Use at session end or when you sense friction accumulated.
/retro "<problem>" — SpotlightFocus on a specific issue described in the argument. Returns proposals only for that issue. Use mid-session for direct fixes (e.g. "the assistant kept forgetting we use bun, not npm").
/retro outcome [session-id|--since N] — Outcome (Schicht D)Replay a past session through the lens of what happened to its output afterwards. Detects: commits reverted, PRs rejected, CI failures, follow-up sessions fixing earlier work, issues filed referencing session files. Use periodically (e.g. monthly) or when you suspect a past decision was wrong.
/retro audit [--scope project|repo|skill] — Constitutional auditCross-session architectural review with a longer horizon (weeks/months). Detects design drift, convention erosion, and patterns that don't manifest as per-session friction but accumulate over time. Same skill, broader window. Use when you want a "is the system on track?" health check, not a "what went wrong this session?" view.
Optional SessionEnd hook (hooks/session-end.json). Activate per user opt-in. Skips trivial sessions via length heuristic.
retro-skill detects friction observable in or near the session. It does not detect:
external-feedback integration if needed.audit mode: per-session retro can't see slow erosion.For these, run /retro outcome (post-hoc) or /retro audit (cross-session). External-feedback ingestion is a future direction.
Mechanical pre-pass — scripts/detect-mechanical.py parses the transcript for 18 deterministic signals (tool errors, retry clusters, output verbosity, tool-call inefficiency, sequential-vs-parallel, correction phrases, prompt/tool sequence repetition, wrong tool choice, skipped verification, upstream failures, permission re-approval, etc.). Output: structured candidate list.
LLM enrichment — Read pre-pass output + relevant transcript excerpts. Add inferential signals (skill capability gaps, wrong skill choice, hallucinations, convention violations, missing skills, repeated mistakes, assumption-without-asking, doc drift). Filter false positives.
Cross-session enrichment (optional) — If ~/.claude-coach/events.sqlite present, query for related events. Otherwise scan ~/.claude/projects/<slug>/*.jsonl for similar friction. Detects: same-friction-again, cross-project patterns, memory drift, ineffective skill updates, follow-up-fix sessions.
3b. Outcome enrichment (Schicht D — only in /retro outcome mode) — Walk forward from session end: git log for revert/amend/supersede on session commits, gh pr view for session PRs (closed without merge? major changes requested?), CI history, follow-up sessions referencing this one. Detects: rejected output, retrospective errors, decisions that didn't survive contact with reality.
3c. Constitutional analysis (only in /retro audit mode) — Cross-session architectural patterns vs declared design: ADR adherence, AGENTS.md rule compliance over recent sessions, coverage trends, skill-inventory drift. Different output class (architectural findings, not friction findings).
Classification — Per finding, map to 1 of 6 destinations using references/classification-heuristic.md.
Discovery (runtime) — For skill-update / new-skill destinations: find installed skills via scripts/find-installed-skills.sh, match by SKILL.md description, resolve source repo URL.
Eval consultation — If matched skill has evals/, read them for context. Propose eval stub alongside skill-update (TDD style).
Proposal generation — Per finding, generate 2-3 paragraph Why + How-to-apply prose. Group by destination.
User approval — Present grouped proposals. Approve / reject / edit per proposal.
Materialization — Per destination:
user-memory → write ~/.claude/projects/<slug>/memory/feedback_<slug>.mdproject-rule → write <project>/docs/feedback/<slug>.md + AGENTS.md index entryskill-update → clone source repo (or use existing ~/p/<name>/main/ worktree), branch, commit, push, open PRnew-skill → invoke skill-repo scaffoldingcheckpoint → YAML entry in target skill's checkpoints.yamlharness-artefact → invoke agent-harness bootstrapReport — Summary of created PRs, written files.
Always: LLM is primary classifier. Patches go to source repos, never cache. Per-private-repo confirmation. Conventional Commits. Preserve commit signing.
Ask first: Skill-match ambiguity. Auto-mode activation. Private repo targets. Dirty worktree fallback.
Never: Auto-merge. Silent writes. Bot attribution in commits/PRs. Skip hooks (--no-verify). Patch the cache directory. Hardcode static skill list. Generate 1000+ candidates.
| File | Purpose |
|---|---|
references/friction-catalog.md | All ~32 friction signals across Schichten A/B/C |
references/destination-taxonomy.md | The six destination categories |
references/classification-heuristic.md | Friction → destination mapping |
references/skill-discovery.md | How to find skills at runtime |
references/patch-workflow.md | Source-repo patching (never cache) |
references/eval-integration.md | Using evals/ for context and TDD stubs |
references/workflow.md | Sweep / Spotlight / Auto modes in detail |