ai-retro-brief

AI Retro Brief

Read the team's AI session retro entries and surface recurring patterns as an actionable one-page brief for their retrospective. The audience is humans walking into a retro — they need ranked patterns, evidence, and proposed actions, not a restatement of every entry.

The root-cause vocabulary is a synchronized copy of the team's canonical taxonomy (docs-first); never reclassify or rename labels here — flag mismatches for the vocabulary review instead.

Input

Read every file in docs/ai-retros/entries/ (sorted by the date in the filename). Each entry carries a **Skill:** version stamp — parse each according to its stamp and note any resulting gaps rather than guessing. Version mapping: count v1.x codebase-friction entries as work-material-friction; v1.x fix lines carry no altitude tag — count them as altitude-unstated; all v2.x entries share the v2.0 format. Legacy format: if a single docs/ai-retros/retro-log.md exists (v1.1 wrote one append-only file, entries under ## YYYY-MM-DD — summary headings), parse its entries too.

If there are fewer than 3 entries, say so and give only a light summary — pattern claims need repetition to mean anything.

Multi-scope rollup: if asked for patterns across several review scopes (repos, accounts, workspaces, engagements), read each scope's docs/ai-retros/entries/ (or its non-repo equivalent), dedup within each scope before comparing across them, and attribute every theme to its scope(s) in the brief.

The brief

Exactly this structure:

# AI Collaboration Retro Brief — <date range>, <N> sessions
**Scope:** <the review scope: repo / product / account / engagement — list the sources if rolled up>
**Skill:** ai-retro-brief v<version from this file's frontmatter>

## Recurring friction
<Themes ranked by frequency × cost. Each theme: prevalence (n of N sessions), representative dated examples, root-cause label, the fixes entries proposed and their altitudes. If a theme is arguably deliberate friction — a control point the team may want to keep (review gates, approval steps) — present it as a keep-or-kill question, not a fix.>

## Root-cause distribution
<Counts per root-cause label, then group them: briefing (ambiguous-instruction, missing-context, incorrect-context, changed-requirements) · documentation (missing-documentation, incorrect-documentation) · work material (work-material-friction — name the concrete material: codebase, account, board, template) · tooling (missing-access-or-tool, environment-friction) · agent (agent-error). State plainly which group dominates — that tells the team whether their attention goes to process, docs, the work material, tooling, or the agent setup. If entries carry altitude tags, also state where proposed fixes are landing.>

## Were suggested fixes adopted?
<For each past "Do this first": did the same friction stop appearing afterward? Unadopted repeat suggestions deserve the team's attention most.>

## Top 3 recommended actions
<Each tied to specific evidence from specific entries, and each naming its altitude. Concrete enough to become a retro action item — owner-assignable, checkable.>

## Trend
<Is friction per session going up, down, or flat? One paragraph, honest about small-sample uncertainty.>