/session-retrospective

name: session-retrospective
description: "Analyzes the current implementation run — evaluates schema effectiveness, delegation alignment, note quality, and plan-to-execution fit. Captures cross-session trends and proposes improvements when patterns repeat. Use after implementation runs, or when user says 'retrospective', 'session review', 'what did we learn', 'analyze this run', 'how did that go', 'evaluate our process', 'wrap up', 'end of session review'. Also use when the retrospective nudge fires after complete_tree."
argument-hint: "[optional: root item UUID] [--dry-run to preview without creating items] [--deep: workflow-backed matching, main session only]"

Session Retrospective

Structured post-implementation analysis. Evaluates the current run across five dimensions, persists findings in MCP, and maintains cross-session trend memory to surface actionable improvement proposals.

---

Step 0 — Mode Check

If `$ARGUMENTS` contains `--dry-run`, set **DRY_RUN = true**. In dry-run mode, perform steps 1-4 and render the report (step 9) but skip steps 5-8 (no MCP item creation, no memory updates). Announce at the top of the report: `**Dry run** — no items created, no memory updated.`

---

Step 1 — Gather Scope

Determine which items to analyze by collecting distributed `session-tracking` notes.

1a. Identify items in scope

**If `$ARGUMENTS` contains a UUID (root item ID):**

query_items(operation="overview", itemId="<root-uuid>")

This returns the root item and its children. Collect all item UUIDs from the overview.

A supplied root UUID is the **authoritative scope** — this covers dispatched mode, e.g. a background agent invoked with the root item ID (see the orchestration context's hook-driven Retrospective dispatch, or the retro-trigger hook's background-agent directive). When a root UUID is supplied, run only this overview call and do **not** run the fallback scan below (neither the `get_context` calls nor the terminal-items search) — the fallback scan applies only when no UUID argument was provided.

**If no root item ID provided:**

Check for a known project root: the `## Project Scope` section of the session context injected by the SessionStart hook, or a `project.rootId` entry in the project-level `.taskorchestrator/config.yaml`. A personal root (`## Personal Scope`, or the user-level config) is not a project root and takes the unscoped branch below.

**If a project rootId is known**, scope both fallback calls to that subtree so concurrent runs in other projects sharing the same DB aren't conflated into this retrospective:

get_context(ancestorId="<rootId>") — active, blocked, stalled items within the project subtree
query_items(operation="search", role="terminal", sortBy="modifiedAt", sortOrder="desc", limit=20, modifiedAfter="<ISO now − 24h>", ancestorId="<rootId>")

**If no project rootId is configured (including personal scope)**, fall back to the prior global behavior (unchanged):

get_context() — active, blocked, stalled items
query_items(operation="search", role="terminal", sortBy="modifiedAt", sortOrder="desc", limit=20, modifiedAfter="<ISO now − 24h>")

Build scope from recently completed items. The 24-hour window is applied by the `modifiedAfter` filter in the call above — list-mode results carry no timestamps (only `id`, `title`, `tags` and role fields), so staleness cannot be judged after the fact.

1b. Collect distributed notes

For each item in scope (up to 20):

query_notes(operation="list", itemId="<uuid>", includeBody=true)

`operation` is **required** — `query_notes` has no default and rejects the call without it (`Missing required parameter: operation`). Use `operation="list"` to enumerate an item's notes.

Extract:

• Notes with key `session-tracking` — these contain per-item outcome, files changed, deviations, friction, observations, and test results
• Notes with key `delegation-metadata` (optional) — orchestrator-recorded model and isolation data (structured provenance line or legacy prose)

1c. Early exit

**If no items are found in scope, or no `session-tracking` notes exist on any item:** Exit early with:

No implementation run data found. Nothing to retrospect — run `/implement` first, then try again.

---

Step 2 — Aggregate Note Data

From the collected `session-tracking` notes, aggregate across all items:

• **Total item count** and **outcome distribution** (success, partial, failed, skipped)
• **Combined files list** — all files changed across items, deduplicated
• **Combined friction list** — all friction entries from all items
• **Combined observations** — notable observations from all items
• **Test results summary** — pass/fail counts across items

If `delegation-metadata` notes exist on any items, extract:

• Model used per delegation (haiku, sonnet, opus)
• Isolation mode (inline, worktree)
• These feed into delegation alignment analysis (step 3b)

**Structured form.** A note whose first line matches `^adapter=\S+( [a-z-]+=\S+)+$` is a structured provenance line, not legacy prose: split the line on spaces, then each token on `key=value`. Each `seat:model` pair inside `seats=` is one delegation, typed by seat rather than guessed from prose — planner → architecture/opus; implementer, test-author → sonnet; declarations-extractor → code reading/sonnet; reviewer → opus; any other seat listed is recorded but not scored. Isolation comes from `isolation=`. `model=` is ignored whenever `seats=` is present (per-seat models supersede the single top-level field). Provenance field order is fixed: `adapter= run= seats= model= isolation= agents= tokens= duration= deferred= in-run-edges= orchestrator-turns=`. Example:

adapter=claude-workflow run=r-20260928-b2d seats=planner:opus,implementer:sonnet,declarations-extractor:sonnet,test-author:sonnet,reviewer:opus model=sonnet isolation=worktree:.claude/worktrees/feat-b2-front-door agents=5 tokens=412800 duration=1860000 deferred=0 in-run-ed