# Retrospective > Run a sprint retrospective for this project. Use when the user says 'retrospective', 'retro', 'close out the sprint', 'what went well', 'generate retro', or wants to generate a RETRO-NN.md file. Reads UPSTREAM-*.md files, recent git history, and conversation context to pre-populate the retrospective. Do NOT use for read-only sprint summaries — use the sprint-review agent for that. - Skill: `voxpelli/retrospective` (Agent Skill) - Install (CLI): `npx skillmds add voxpelli/retrospective` - Raw SKILL.md: https://api.skillmd.com/api/skills/voxpelli/retrospective/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: voxpelli (https://skillmd.com/u/voxpelli) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/voxpelli/retrospective --- # Sprint Retrospective Generate a sprint retrospective for this project. If the project `CLAUDE.md` has a Sprint retrospectives section with a template, use it; otherwise use the template below. ## Context Retrospective files are named `RETRO-NN.md` in the project root. Each covers one sprint's worth of work. ## Workflow ### Beads availability Beads is available iff a `.beads/` directory exists **and** `command -v bd` succeeds; this component is **Tier C** per CLAUDE.md `### Beads-availability convention`. Steps 1–3 and the UPSTREAM / SYNERGY / Basic Memory parts of the trend review are beads-independent and run unchanged. When beads is **unavailable**, the three bd-dependent steps **degrade and announce** (never skip silently): - **Health audit (step 4)** — replace the `bd` health checks with an announced skip line in the RETRO `### Health audit` subsection (see step 4). - **Findings (step 5)** — append a `### Follow-ups (untracked)` task list to the RETRO file instead of running `bd create` (see step 5). - **Decision capture (step 5)** — record decisions inline as a `### Decisions` block in the RETRO file instead of `bd create --type=decision` (see step 5). ### 1. Determine sprint number ```bash ls RETRO-*.md | sort -V | tail -1 ``` Extract the highest sprint number and increment by 1. **This file count is canonical for the trend-review heuristic in step 4** — do not substitute a user-asserted topic number, release number, or `bd` sprint label. If `RETRO-NN.md` count is divisible by 4, this IS a trend-review sprint regardless of how the work is verbally framed. ### 2. Gather context Run these in parallel: **Recent commits since last retro:** ```bash # Anchor to the commit that created/last modified the previous RETRO file. # Edge cases that both result in full-history range (correct for Sprint 1): # 1. No prior RETRO-*.md files exist yet # 2. RETRO files are gitignored — git log -- RETRO-*.md returns empty # In both cases the inner git log returns empty, making the range "..HEAD" # which shows all commits — the right behavior for a first retrospective. git log --oneline "$(git log -1 --format=%H -- RETRO-*.md)"..HEAD --no-merges ``` **Current upstream status:** - Glob for all `UPSTREAM-*.md` files and read them - Count open items per file and per section **Current synergy status:** - Glob for all `SYNERGY-*.md` files and read them - Count open entries per file and per section - Highlight actionable items: Extraction Candidates with `Readiness: ready`, Divergences with `Convergence path: adopt-theirs` or `propose-shared`, They Have / We Don't with `Priority: adopt-soon` - Note any Shared Patterns with `Status: drifting` **Recent conversation context:** - Review the current session for friction, workarounds, discoveries, and decisions made during development **Test and coverage status:** Check `package.json` scripts for a test command. Try in order: 1. `npm test` (if a `test` script exists) 2. `npm run test:node` (if a `test:node` script exists) 3. `npm run test` (if a `test` script exists under another variant) 4. `npm run check` (if a `check` script exists — used by validation-suite projects like this one, vp-knowledge, vp-git) Run the first that exists and show the last 5 lines of output. ### 3. Draft the retrospective Create `RETRO-{N}.md` using this template (omit `### Synergy observations` if no SYNERGY-\*.md files were found in step 2): ```markdown ## Sprint {N} Retrospective — {YYYY-MM-DD} ### What went well - ... ### What could improve - ... ### Upstream observations - ... ### Synergy observations - **Extraction Candidates ready:** - **Drifting shared patterns:** - **Active convergence paths:** - **New patterns logged this sprint:** - **Stale entries flagged:** ### Lessons learned - ... ``` **Section guidelines:** - **What went well** — concrete wins: bugs caught, patterns established, clean commits, test improvements. Reference specific files/commits. Focus on process and engineering quality, not just features shipped. - **What could improve** — honest assessment of friction, false starts, wasted effort. Not a blame list — focus on systemic issues and what would prevent recurrence. - **Upstream observations** — summarize current state of all UPSTREAM files. Log any NEW friction discovered in the session to the appropriate UPSTREAM file using `/upstream-tracker` workflow 1 (Log a new entry). Review recent session work — did any workarounds or local extensions get built this sprint that are self-contained enough to contribute back? If yes, log via `/upstream-tracker` workflow 1 (Log a new entry) with type "Upstream Opportunity". Note trends across packages. Flag stale items (>3 months old). - **Synergy observations** — summarize current state of all SYNERGY files. Log any NEW cross-project observations discovered in the session to the appropriate SYNERGY file using `/synergy-tracker` workflow 1 (Log a synergy entry). Report extraction candidates with `Readiness: ready` as sprint-actionable. If any candidates were acted on this sprint, record the outcome. Review recent session work — did any implementation reveal shared patterns with sibling projects, or produce logic worth extracting into a shared package? If yes, log via `/synergy-tracker` workflow 1 (Log a synergy entry). Note trends across sibling projects. Flag stale entries (>3 months old). If no SYNERGY files exist, omit this section from the generated RETRO-NN.md entirely. - **Lessons learned** — reusable insights. Each should be a principle that future sessions can apply, not a one-off fact. Format: **Bold principle** — supporting evidence from this sprint. ### 4. Check for trend review If this is every 4th sprint (Sprint 4, 8, 12, ...), also perform a trend review: (Sprint number is the file count from step 1, not a topic-asserted number.) **UPSTREAM files:** Review all `UPSTREAM-*.md` files — identify common trends, evaluate whether open items are still valid, delete non-vendor files with no remaining entries. **SYNERGY files:** Review all `SYNERGY-*.md` files — identify stale entries (>3 months), evaluate whether Shared Patterns are still `aligned` or have drifted, check if Extraction Candidates with `Readiness: ready` have been acted on, and review whether `adopt-theirs` Divergences have been adopted. **Health audit:** Run bd's full health vocabulary in parallel — five focused checks covering infrastructure, template compliance, lifecycle hygiene, reference integrity, and dependency-graph integrity. Each command emits JSON for stable parsing. Surface counts plus the top 3–5 affected items per check in the generated `RETRO-NN.md` under a `### Health audit` subsection. **Beads unavailable (Tier C):** skip the `bd` health checks and render the subsection as a single announced line instead — `- _Skipped — beads not active in this project._` The UPSTREAM and SYNERGY trend-review parts above and the Basic Memory graph health below are beads-independent and still run. ```bash bd doctor --json # Infrastructure: outdated hooks, gitignore drift, remote config bd lint --json # Template compliance: issues missing required sections per type bd stale --json # Lifecycle: issues with no recent activity bd orphans --json # Reference integrity: refs in commits but issue still open bd graph check --json # Dependency graph: cycles, dangling refs (schema_version: 1) ``` Per-check guidance: - **`bd doctor --json`** — parse `warnings[]`. Auto-fix is gated on user consent: present the warning list and prompt before invoking `bd doctor --fix --yes`. Never auto-apply. Note the **false positive** on the Claude Hook Completeness check — it sometimes flags hooks that are intentionally absent or installed via a plugin (see `UPSTREAM-brew--beads.md` for the open friction entry); skip the prompt for that warning class until it is resolved upstream. - **`bd lint --json`** — parse `issues[]`. No auto-fix; lint findings require human triage. List affected issue IDs with the missing section names so the maintainer can update them (e.g., `bd update ` adding `## Acceptance Criteria` to a `feature`). - **`bd stale --json`** — parse `issues[]`. No auto-fix; suggest one of three human actions per issue: defer (lower priority), close (no longer relevant), or work (claim and progress). - **`bd orphans --json`** — parse `issues[]`. If `--json` is unavailable on the installed `bd` version, fall back to text parsing of `bd orphans` output. No auto-fix; suggest closing the issue or unmarking the orphan reference. - **`bd graph check --json`** — parse the schema-versioned envelope (`{"clean": bool, "cycles": [...] | null, "schema_version": 1, "summary": {...}}`). When `clean: false`, surface cycle paths and dangling refs with fix recommendations (typically `bd dep remove ` to break a cycle, or `bd close` for stale references — `bd dep` uses subcommands, not flag-form). No auto-fix. Render in the RETRO file as: ```markdown ### Health audit - **Infrastructure (`bd doctor`):** {N} warnings — {top items, or "clean"} - **Template compliance (`bd lint`):** {N} issues — {top items, or "clean"} - **Lifecycle (`bd stale`):** {N} stale issues — {top items, or "clean"} - **Reference integrity (`bd orphans`):** {N} orphans — {top items, or "clean"} - **Dependency graph (`bd graph check`):** {clean | N cycles, top items} - **Stats (`bd stats`):** {total / open / in_progress / closed / ready / blocked counts} - **Blocked review (`bd blocked`):** {list blocked issues; for each, run `bd show ` to identify its blockers and flag any blockers whose status is currently `closed` — these need `bd update` to re-evaluate readiness} - **`bd compact` candidates:** {manual judgment — list closed-issue count and flag if >150 closed since last compact, otherwise "below threshold"} ``` **Basic Memory graph health** (via Basic Memory MCP tools): 1. Run the knowledge-gardener agent for automated audit (orphans, schema, stale notes, duplicates) 2. Validate both schemas: call `mcp__basic-memory__schema_validate` with `note_type="npm_package"` and again with `note_type="engineering"` 3. Call `mcp__basic-memory__schema_diff` on both types to detect drift (new observation categories in use but not in schema, or schema fields rarely used) 4. If notes cluster around a new unschemaed `type`, call `mcp__basic-memory__schema_infer` and consider creating a new schema 5. Verify all notes have: frontmatter `type` and `tags`, `## Observations`, `## Relations` 6. Flag notes missing any layer; fix or create beads issues **Basic Memory notes (project-independent knowledge base):** Basic Memory is a cross-project knowledge store — notes there must be written from a general engineering perspective, not referencing project-specific file paths, table names, or project structure. Vendor package names (e.g., `@scope/vendor-package`) are fine since they're real npm packages. Mentioning this project by name is okay when genuinely relevant — just don't make notes only useful within this project. Call `mcp__basic-memory__search_notes` and: - Update notes that have been superseded by new learnings this sprint - Remove notes that are too project-specific — generalize or delete - Check for duplicate notes across directories and merge them - Verify tags are consistent and discoverable ### 5. Create beads issues from findings Review the "What could improve" and "Lessons learned" sections for actionable items that aren't already tracked. Create beads issues for each: ```bash bd create "..." -t bug|task|feature|chore -p N --description "..." ``` (`-t` = type; `-p` = priority: 0=critical, 1=high, 2=medium, 3=low, 4=backlog) Include code quality issues, process improvements, and any findings that need follow-up work. Skip items that are purely observational or already have open issues. **Beads unavailable (Tier C):** there is no backlog to file into — instead append a `### Follow-ups (untracked)` task list to the `RETRO-NN.md` file, one checkbox per actionable finding, so the items are still captured: ```markdown ### Follow-ups (untracked) - [ ] {finding} — {type}, {priority} ``` Announce that follow-ups were written to the RETRO file rather than created as beads (they can be filed later if beads is adopted). **Decision capture.** When a sprint outcome is a *decision* (an architectural or product choice with explicit rationale and rejected alternatives) rather than a task, bug, or feature, file it as the `decision` issue type — not a generic task. Decision-typed issues are queryable as ADRs and follow the supersede workflow. Recognize a decision when the sprint surfaced any of: - A choice between two or more viable approaches with rationale recorded - A reversal or revision of a previous decision (use `supersede` to link) - A constraint accepted (e.g., "we will not support X until Y") that future work must respect For each decision, prompt the user to either: 1. **Invoke the upstream `/beads:decision` slash command** — preferred path. The command lives in the upstream `beads` plugin (NOT vp-beads) and wraps `bd create --type=decision` with structured templates plus record/list/show/supersede operations. Use this for the full lifecycle. 2. **Or create directly via `bd create --type=decision`** with the four-section template: ```markdown ## Decision ## Rationale ## Alternatives Considered ## Affects ``` The first three are required by `validation.on-create=error`; `## Affects` is conventional and lists impacted components, files, or future work. **Lifecycle:** decision-typed issues stay **open** while the decision is in force. `open` = active decision, `closed` = superseded or reversed (NOT closed-on-create). The retrospective never auto-closes decisions — the upstream `/beads:decision` slash command handles supersession when the decision is later revised. Cross-reference that command for the full lifecycle (record/list/show/supersede) rather than implementing it here. **Beads unavailable (Tier C):** record the decision inline in `RETRO-NN.md` as a `### Decisions` block carrying the same four sections, instead of `bd create --type=decision`: ```markdown ### Decisions **{decision title}** - **Decision:** {the choice made} - **Rationale:** {why} - **Alternatives considered:** {rejected options} - **Affects:** {impacted components, files, or future work} ``` Announce that the decision was captured in the RETRO file; it can be promoted to a `decision`-typed bead later if beads is adopted. ### 6. Knowledge gap audit Run `/knowledge-gaps` (if vp-knowledge is installed): `/knowledge-gaps` scans all package manifests in the project (npm, Rust crates, Go modules, PHP Composer, Python PyPI, Ruby gems) and tool manifests (Brewfile, GitHub Actions workflows, Dockerfile, VSCode extensions). It cross-references each dependency against Basic Memory notes to identify undocumented packages and tools. Steps: 1. Run `/knowledge-gaps` — it handles all manifest types automatically. If vp-knowledge is not installed, skip this step and note in the retrospective under "What could improve" that knowledge gap coverage was not audited. 2. Include Tier 1 gaps in the retrospective under "What could improve" 3. Create beads issues for the top 3 undocumented packages or tools ### 7. Write project-independent learnings to Basic Memory Basic Memory is a **cross-project knowledge base** — it persists across all repositories and sessions. Notes written here must be generalizable engineering knowledge, not project-specific implementation details. Ask: "Would this note help me on a completely different project using the same technology?" If yes, write it. If it only makes sense in the context of this codebase, it belongs in `MEMORY.md` or the project `CLAUDE.md` instead. For each learning, search first, then create or update: - If no matching note exists: call `mcp__basic-memory__write_note` to create it - If a note exists with new content: call `mcp__basic-memory__read_note` first to get exact content, then call `mcp__basic-memory__edit_note` with `find_replace` or `replace_section` — never call `write_note` on an existing note (it requires `overwrite=True` and risks replacing the full note content) Organize by engineering domain: | Directory | Topics | | ----------------------- | ------------------------------------------ | | `engineering/fastify/` | Plugin patterns, lifecycle, error handling | | `engineering/frontend/` | Web components, CSS, dark mode, SSR, a11y | | `engineering/database/` | Query patterns, migrations, PostgreSQL | | `engineering/testing/` | Test conventions, infrastructure, coverage | | `engineering/tooling/` | Linter config, build pipelines, knip | | `engineering/agents/` | Orchestration, workflow, quality gates | **Guidelines:** - Only write notes for patterns confirmed this sprint — not speculative - Use concrete code examples, not abstract principles - Tag notes for discoverability - **No project-specific internals** — replace project file paths with generic descriptions (e.g., "route handler file" not "lib/routes/settings.js"), omit table names, and describe patterns in terms of the technology, not the application. Referencing vendor packages by npm name (e.g., `@scope/vendor-package`) is fine — they're real published packages. Mentioning this project by name is okay when genuinely relevant — just don't make the note only useful within this project. - **Division of labor with upstream-tracker and synergy-tracker.** This step writes `engineering/*` notes (patterns, conventions, lessons learned). For upstream friction about specific packages or tools, use `/upstream-tracker` workflow 6 (Promote to Basic Memory) instead — it writes to the `## Upstream Friction` section of entity notes (`npm/*`, `brew/*`, etc.), avoiding duplication. For cross-project extraction opportunities tracked in `SYNERGY-*.md` files, use `/synergy-tracker` — it manages the extraction lifecycle and any corresponding Basic Memory notes. For packages not yet in Basic Memory, suggest `/package-intel` or `/tool-intel` for enrichment first. **NEVER write to `engineering/agents/vp-plugins-*` paths from this step** — those are sibling-relationship notes owned by `/synergy-tracker` workflow 5 (Promote to Basic Memory). For cross-project lessons that touch a sibling-relationship, log via `/synergy-tracker` workflow 1 (Log a synergy entry) and let workflow 5 (Promote to Basic Memory) promote them; do not shortcut the relationship-note ownership boundary by writing `engineering/agents/vp-plugins-*` directly here. ### 8. Suggest documentation updates After writing the retro, suggest updates to: - Project `CLAUDE.md` — new conventions, gotchas, or commands discovered - `MEMORY.md` — stable patterns confirmed across sprints - `README.md` — if project structure or commands changed Present suggestions to the user for approval before editing.