Retrospective

You are reviewing past work to extract patterns that make future work better. This is not a report for its own sake — every finding should either become a learning (fed to /learn) or be acknowledged as already captured.

The goal: leave HQ smarter than you found it.

Step 0: Mode + Company Resolution

Mode detection:

• If $ARGUMENTS contains --session → SESSION mode
• If $ARGUMENTS contains a project slug → PROJECT mode
• If $ARGUMENTS is empty or ambiguous → AskUserQuestion: "A) Review a specific project. B) Review recent session work."

Company resolution: Check if the first word matches a company slug in companies/manifest.yaml. Same pattern as /brainstorm:

1. If matched: set {co}, strip from args, load policies
2. If not matched: infer from cwd or project slug location
3. If still ambiguous: ask

Announce: Mode: {PROJECT|SESSION} | Company: {co}

Step 1: Data Collection

PROJECT Mode

Read these data sources (skip gracefully if any don't exist):

# 1. The PRD
# Read companies/{co}/projects/{slug}/prd.json
# Extract: stories (titles, statuses), metadata (dates, linear IDs)

# 2. Git history for the project
git log --oneline --since="{prd.createdAt}" -- {repo paths if known}

# 3. Workspace threads mentioning this project
# Glob pattern: workspace/threads/*{slug}*.json
# Read each, extract conversation_summary + files_touched

# 4. Audit log events
grep '"{slug}"' workspace/metrics/audit-log.jsonl | tail -50

# 5. Model usage (worker activity)
grep '"{slug}"' workspace/metrics/model-usage.jsonl | tail -50

# 6. Orchestrator state (if exists)
# Read workspace/orchestrator/{slug}/state.json

# 7. Brainstorm (if exists)
# Read companies/{co}/projects/{slug}/brainstorm.md

SESSION Mode

# 1. Recent threads (last 24h)
# List workspace/threads/ sorted by modification time, read top 5-10

# 2. Recent learnings
# List workspace/learnings/ sorted by modification time, read top 10

# 3. Recent audit log entries (last 24h)
tail -100 workspace/metrics/audit-log.jsonl

# 4. Recent git activity
git log --oneline --since="24 hours ago"

# 5. Current git status
git status

Present collection summary:

Data collected:
- Stories: {N} found ({done}/{total})
- Threads: {N} found
- Audit events: {N} found
- Git commits: {N} in scope
- Workers used: {list or "none tracked"}

Step 2: Analysis

PROJECT Mode — Analyze These Dimensions

1. Story Completion

Story	Title	Status	Retries	Workers
US-001	...	done/failed/stalled	N	...

2. Worker Usage

Worker	Tasks Assigned	Success Rate
...	N	N/N

Which workers carried the most load? Any worker used on >70% of stories?

3. Timeline

• PRD created: {date}
• First story started: {date}
• Last story completed: {date}
• Total elapsed: {N days}
• Stories per day: {rate}

4. Quality Gate Outcomes

• How many stories passed on first attempt?
• How many required retries? What caused retries?
• Quality gate failure rate: {N}%

5. File Churn

• Files touched across most stories (indicates scope underestimation or tight coupling)
• Any files touched by >50% of stories? Flag as architectural hotspot

6. Learnings Already Captured

• Check workspace/learnings/ and companies/{co}/policies/ for rules created during this project
• List them — don't re-capture what's already been learned

SESSION Mode — Analyze These Dimensions

1. What Was Accomplished

• List each completed task/thread with 1-line summary
• Any tasks started but not finished?

2. Files Touched

• Aggregate across all session threads
• Any surprising files? (files outside expected scope)

3. Failures or Retries

• Any tool call failures or retries in audit log?
• Any handoff/checkpoint events?

4. Time Distribution

• Rough breakdown: planning vs building vs debugging vs reviewing

5. Environment levers

Use the same seven levers as the /handoff deficiency scan (Step 2b of .claude/skills/handoff/SKILL.md). Unlike /handoff, retro reads the record: threads, learnings, the audit log, and git history from Step 1. Flag a lever only when that record shows the environment (not the task) slowed or misled the work.

lever	use when
navigation	Finding the right file, script, or doc took repeated searches or wrong turns.
automated-checks	A test, lint, hook, or CI check was missing, flaky, slow, or misleading.
coding-standards	A convention was unclear, contradictory, or undocumented.
steering-bloat	Injected policies, reminders, or context crowded out what mattered or got truncated.
tool-economy	A tool or command cost far more calls, output, or retries than the job needed.
no-ops	A command, hook, or step ran and did nothing useful.
information-access	Needed information, access, or a credential was unavailable or hard to reach.

Write each finding with the handoff item fields (lever, kind, severity, summary, evidence, proposed_fix; kind is hq-core, local-setup, or repo; evidence is required) to a temp file, for example mktemp workspace/threads/.handoff-tmp/retro-deficiencies.XXXXXX. Then merge in the deficiencies[] arrays that /handoff stored in thread files modified in the last 24h:

bash core/scripts/retro-merge-deficiencies.sh --root "$PWD" \
  --retro-json "{retro_deficiencies_file}" \
  ${HQ_ACTIVE_COMPANY:+--company "$HQ_ACTIVE_COMPANY"} \
  --out "{retro_thread_file}"

The script dedupes by lever and summary (the retro's own item wins), drops items without evidence, tags each item with its source, and writes {retro_thread_file}: a thread-shaped file with the merged deficiencies[] and the newest thread's system_info. Step 5 reports from it and Step 6 files from it. When a company is bound, --company limits the merge to threads whose metadata.company lists it, so the analysis stays inside the resolved company's threads.

Step 3: Pattern Detection

Flag these patterns when evidence supports them:

Pattern	Signal	Implication
Complexity underestimated	Story with 2+ retries	PRD story sizing was off — capture as sizing heuristic
Worker overuse	Same worker >70% of stories	Consider making it a default in PRD template
Quality gate failures	>20% failure rate	Upstream planning issue — stories shipped before ready
Undeclared files	Stories with 0 files[] in PRD	File locking risk — add to PRD template guidance
Scope creep	Files touched outside story scope	Scope definition was too narrow or coupling wasn't anticipated
Architectural hotspot	Same file in >50% of stories	This file needs refactoring or better abstraction
Missing test coverage	Quality gate test failures	Test strategy needs strengthening for this area
Session fragmentation	3+ handoffs for one project	Context overhead — consider longer sessions or better checkpoints
Tool mismatch	Repeated failures with specific tool/MCP	Tool setup issue or wrong tool for the job

Only flag patterns with clear evidence. Don't speculate.

Step 4: Learning Extraction

For each detected pattern:

1. Generate a learning candidate — state the rule in ALWAYS/NEVER format:

   • e.g., "ALWAYS declare file dependencies in prd.json stories when the project touches shared modules"
   • e.g., "NEVER estimate stories touching {area} as S — they're always M minimum"

2. Classify scope:

   • Project-specific → note it but don't create a policy (too narrow)
   • Company-scoped → companies/{co}/policies/
   • Global → core/policies/

3. Check for duplicates — grep existing policies for similar rules

4. Present to user:

   Learning candidates ({N} found):
   
   1. {rule} — Scope: {company|global} — {new|already exists}
   2. {rule} — Scope: {company|global} — {new|already exists}
   ...
   
   Run /learn for new learnings? [Y/n]
   

5. If user approves: suggest running /learn with each new learning. Do NOT write policy files directly — /learn handles dedup, formatting, and injection.

Step 5: Write Retro Report

Output to workspace/reports/{slug}-retro.md:

# {Project/Session Title} — Retrospective

**Date:** {ISO8601}
**Mode:** Project | Session
**Company:** {co}
**Duration:** {start date} → {end date}

## Summary

{2-3 sentence summary of what happened — scope, outcome, notable events}

## Stories (PROJECT mode)

| Story | Title | Status | Retries | Workers Used |
|-------|-------|--------|---------|-------------|
| US-001 | ... | done | 0 | frontend-designer |

**Completion rate:** {done}/{total} ({%})

## Worker Usage (PROJECT mode)

| Worker | Tasks | Coverage |
|--------|-------|----------|
| ... | N | N% |

## Timeline (PROJECT mode)

- PRD created: {date}
- First story: {date}
- Last story: {date}
- Elapsed: {N} days
- Velocity: {stories/day}

## Session Summary (SESSION mode)

| Thread | Summary | Files | Outcome |
|--------|---------|-------|---------|
| T-... | ... | N files | completed/partial |

## Patterns Detected

{For each pattern with evidence:}

### {Pattern Name}
**Signal:** {what was observed}
**Evidence:** {specific data point}
**Implication:** {what this means for future work}

## Quality Gate Outcomes (PROJECT mode)

- First-pass success rate: {%}
- Total retries: {N}
- Most common failure: {category}

## Learnings

| # | Rule | Scope | Status |
|---|------|-------|--------|
| 1 | {rule} | {scope} | new / already captured |

## Environment Deficiencies (SESSION mode)

Merged from this retro and thread `deficiencies[]` (last 24h). Same fields as the `/handoff` array.

| lever | kind | severity | summary | evidence | proposed_fix | source |
|---|---|---|---|---|---|---|
| {lever} | {hq-core / local-setup / repo} | {high / medium / low} | {one line} | {what concretely happened} | {change or command} | {retro or thread file} |

Write "None found." when the merged array is empty.

## What Went Well

- {Specific thing that worked — be concrete, not generic}

## What to Improve

- {Specific thing to do differently — actionable, not vague}

## Open Questions

- {Anything unresolved that should be addressed in the next project}

Step 6: Wrap Up

qmd update 2>/dev/null || true

SESSION mode, hq-core deficiencies. When {retro_thread_file} has any kind: "hq-core" item, offer to file them (ask; never file without a yes). Reuse the /handoff scripts with {retro_thread_file} as the thread:

bash core/scripts/handoff-builder-route.sh --root "$PWD" --thread "{retro_thread_file}"

• route: public (...): offer /hq-bug. On yes, run bash core/scripts/handoff-autofile.sh --thread "{retro_thread_file}" --root "$PWD". It files one hq feedback bug report, applies the 7-day dedupe ledger and the secret scan, and prints one filed: / skipped: / aborted: / failed: line. Keep it as {file_result}.
• route: builder with brief: <path>: offer a staging PR. On yes, dispatch one visible fix agent with that brief exactly as /handoff Step 4.5 "Builder route" does (same prompt, never merge, never push to main). Keep its pr: line as {file_result}.
• brief: none (...), no hq-core items, or the user declines: {file_result} is none (<reason>).

Remove the temp files from Step 2 afterwards.

Print:

Retro complete: {title}
Report: workspace/reports/{slug}-retro.md
Patterns detected: {N}
New learnings: {N} (run /learn to capture)
Environment deficiencies: {N} ({hq-core N}) — {file_result}

---

Rules

• Read-only analysis — retro does not modify project files, prd.json, or board.json. It writes only its own report and temp files, and files hq-core deficiencies only after the user says yes
• Evidence-backed patterns only — do not flag patterns without specific data points from Steps 1-2
• Delegate learning capture — suggest /learn, do not write policy files directly
• No re-capture — check existing policies before proposing a learning. Duplicates waste context
• Both modes are valid — SESSION mode is lighter but still valuable. Not every retro needs a full project
• Company isolation — scope all data collection to the resolved company. Never mix cross-company data
• Do NOT create task lists or enter planning mode — this is a focused analysis, not a project
• Honest assessment — if a project went poorly, say so. Retros that only praise are useless
• Actionable over comprehensive — 3 concrete learnings beat 10 vague observations