Structured Retrospective

Analyze what happened in the current session, extract learnings, and turn them into durable improvements — rules, feedback memories, or GitHub issues.

Follow every step in order. Stop and report if any step fails.

Core Principle

Learnings decay. If a retrospective doesn't happen immediately after the work, the insights are lost. Capture them while context is fresh, classify them by type, and route them to the right destination so they compound over time.

The Iron Law

NO RETRO WITHOUT EVIDENCE.
Every Keep, Problem, and Action must cite a specific event from the session — not a general feeling.

When to Use

• After completing parallel/batch work (taskmaestro waves, swarm, ultrawork)
• After a multi-step plan execution (PLAN → ACT → EVAL cycle)
• After a significant debugging session
• After any session where something surprising happened (good or bad)
• When the user explicitly asks to reflect on recent work

Don't use when:

• The session was trivial (single file edit, quick fix)
• No context.md or session history exists to analyze

Step 1: Gather Session Context

Read the session history from docs/codingbuddy/context.md:

cat docs/codingbuddy/context.md

If the file does not exist or is empty, check for alternative sources:

1. $ARGUMENTS — the user may pass a file path or description
2. Git log for recent commits on the current branch: git log --oneline -20
3. If no context is found, stop and tell the user: "No session history found. Run a PLAN → ACT cycle first, or pass a context file as argument."

Collect:

• Tasks attempted — what was planned
• Tasks completed — what actually shipped
• Tasks failed or blocked — what didn't work and why
• Timeline — rough sequence of events

Step 2: Keep Analysis

Identify what went well. For each item:

Ask:

• What practices should we repeat?
• What decisions saved time or prevented issues?
• What tools or patterns proved valuable?

Output as a numbered list:

### Keeps
1. **[What]** — [Evidence]. [Why it worked].
2. ...

Step 3: Problem + Root-Cause Analysis

Identify what went wrong or could be improved. For each item:

Severity classification:

Output as a numbered list:

### Problems
1. **[Severity]** [What] — [Evidence]. Root cause: [5-Whys result].
2. ...

Step 4: Classify Learnings

For every Keep and Problem, classify the learning into exactly one category:

Output as a table:

### Classification

| # | Learning | Category | Destination | Action |
|---|----------|----------|-------------|--------|
| 1 | [summary] | rule | CLAUDE.md | Add rule: "..." |
| 2 | [summary] | memory | feedback_xxx.md | Save feedback: "..." |
| 3 | [summary] | automation | GitHub issue | Create issue: "..." |
| 4 | [summary] | none | — | — |

Step 5: Generate Action Items

For each learning classified as rule, memory, or automation, create a concrete action item:

For rule items:

• Draft the exact rule text
• Identify the target file (CLAUDE.md, .ai-rules/rules/core.md, etc.)
• Format: Add to [file]: "[rule text]"

For memory items:

• Draft the feedback memory content following the project's memory format:

  ---
  name: feedback_[topic]
  description: [one-line description]
  type: feedback
  ---
  
  [Rule itself]
  
  **Why:** [reason from the session]
  **How to apply:** [when this guidance kicks in]

For automation items:

• Draft a GitHub issue body compatible with /plan-to-issues:

  ## Purpose
  [What this automation prevents or enables]
  
  ## Changes
  - [file or component to create/modify]
  
  ## Acceptance Criteria
  - [ ] [verifiable criterion]

Step 6: Save Feedback Memories

For each memory classified item from Step 4:

1. Check if a similar feedback memory already exists:

   ls ~/.claude/projects/*/memory/feedback_*.md 2>/dev/null
   grep -rl "[keyword]" ~/.claude/projects/*/memory/ 2>/dev/null

2. If exists → update the existing file
3. If new → create the memory file and update MEMORY.md index

Rules:

• One memory per learning — don't bundle unrelated learnings
• Use the project's established memory format (frontmatter + content)
• Memory name must be descriptive: feedback_[topic].md

Step 7: Create GitHub Issues (Optional)

For each automation classified item from Step 4:

1. Ask the user: "Create GitHub issues for [N] automation items? (y/n)"
2. If yes, for each item create an issue:

   gh issue create --title "feat: [title]" --body "$(cat <<'EOF'
   ## Purpose
   [from Step 5]
   
   ## Changes
   [from Step 5]
   
   ## Acceptance Criteria
   [from Step 5]
   EOF
   )"

3. If the user declines, print the issue drafts so they can create them later.

Rules:

• Never create issues without user confirmation
• Add label feat for new automations, improvement for enhancements
• Link back to the session context if relevant

Step 8: Report

Print a summary of the retrospective:

## Retro Summary

### Session
- **Branch**: [current branch]
- **Commits**: [N commits in session]
- **Context file**: docs/codingbuddy/context.md

### Results
- **Keeps**: [N] identified
- **Problems**: [N] identified ([critical], [high], [medium], [low])
- **Actions**: [N] total
  - Rules added/updated: [N]
  - Feedback memories saved: [N]
  - GitHub issues created: [N]
  - No action needed: [N]

### Action Items
1. [action summary] → [destination] ✅ Done / 📋 Draft
2. ...