Retro

---
name: retro
description: 'Extract learnings from completed work. Trigger phrases: "run a retrospective", "extract learnings", "what did we learn", "lessons learned", "capture lessons", "create a retro".'
skill_api_version: 1
metadata:
  tier: knowledge
  dependencies:
    - vibe  # optional - can receive --vibe-results
---

# Retro Skill

**YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.**

Extract learnings from completed work, propose proactive improvements, and feed the knowledge flywheel.

## Flags

| Flag | Default | Description |
|------|---------|-------------|
| `--quick "text"` | off | Quick-capture a single learning directly to `.agents/learnings/` without running a full retrospective. Absorbs the former learn skill. |
| `--vibe-results <path>` | off | Incorporate validation findings from a prior `/vibe` run |

## Quick Mode

Given `/retro --quick "insight text"`:

### Quick Step 1: Generate Slug

Create a slug from the content: first meaningful words, lowercase, hyphens, max 50 chars.

### Quick Step 2: Write Learning Directly

**Write to:** `.agents/learnings/YYYY-MM-DD-quick-<slug>.md`

```markdown
---
type: learning
source: retro-quick
date: YYYY-MM-DD
---

# Learning: <Short Title>

**Category**: <auto-classify: debugging|architecture|process|testing|security>
**Confidence**: medium

## What We Learned

<user's insight text>

## Source

Quick capture via `/retro --quick`
```

This skips the pool pipeline — writes directly to learnings, not `.agents/knowledge/pending/`.

### Quick Step 3: Confirm

```
Learned: <one-line summary>
Saved to: .agents/learnings/YYYY-MM-DD-quick-<slug>.md

For deeper reflection, use `/retro` without --quick.
```

**Done.** Return immediately after confirmation.

---

## Full Retrospective

## Execution Steps

Given `/retro [topic] [--vibe-results <path>]`:

### Step 1: Identify What to Retrospect

**If vibe results path provided:** Read and incorporate validation findings:
```
Tool: Read
Parameters:
  file_path: <vibe-results-path>
```

This allows post-mortem to pass validation context without re-running vibe.

**If topic provided:** Focus on that specific work.

**If no topic:** Look at recent activity:
```bash
# Recent commits
git log --oneline -10 --since="7 days ago"

# Recent issues closed
bd list --status closed --since "7 days ago" 2>/dev/null | head -5

# Recent research/plans
ls -lt .agents/research/ .agents/plans/ 2>/dev/null | head -5
```

### Step 2: Gather Context

Read relevant artifacts:
- Research documents
- Plan documents
- Commit messages
- Code changes

Use the Read tool and git commands to understand what was done.

### Step 3: Identify Learnings

**If vibe results were provided, incorporate them:**
- Extract learnings from CRITICAL and HIGH findings
- Note patterns that led to issues
- Identify anti-patterns to avoid

Ask these questions:

**What went well?**
- What approaches worked?
- What was faster than expected?
- What should we do again?

**What went wrong?**
- What failed?
- What took longer than expected?
- What would we do differently?
- (Include vibe findings if provided)

**What did we discover?**
- New patterns found
- Codebase quirks learned
- Tool tips discovered
- Debugging insights

### Step 4: Extract Actionable Learnings

For each learning, capture:
- **ID**: L1, L2, L3...
- **Category**: debugging, architecture, process, testing, security
- **What**: The specific insight
- **Why it matters**: Impact on future work
- **Confidence**: high, medium, low

### Step 5: Write Learnings

**Write to:** `.agents/learnings/YYYY-MM-DD-<topic>.md`

```markdown
---
id: learning-YYYY-MM-DD-<slug>
type: learning
date: YYYY-MM-DD
category: <category>
confidence: <high|medium|low>
---

# Learning: <Short Title>

## What We Learned

<1-2 sentences describing the insight>

## Why It Matters

<1 sentence on impact/value>

## Source

<What work this came from>

---

# Learning: <Next Title>

**ID**: L2
...
```

### Step 5.5: Classify Learning Scope

For each learning extracted in Step 5, classify:

**Question:** "Does this learning reference specific files, packages, or architecture in THIS repo? Or is it a transferable pattern that helps any project?"

- **Repo-specific** → Write to `.agents/learnings/` (existing behavior from Step 5). Use `git rev-parse --show-toplevel` to resolve repo root — never write relative to cwd.
- **Cross-cutting/transferable** → Rewrite to remove repo-specific context (file paths, function names, package names), then:
  1. Write abstracted version to `~/.agents/learnings/YYYY-MM-DD-<slug>.md` (NOT local — one copy only)
  2. Run abstraction lint check:
     ```bash
     file="<path-to-written-global-file>"
     grep -iEn '(internal/|cmd/|\.go:|/pkg/|/src/|AGENTS\.md|CLAUDE\.md)' "$file" 2>/dev/null
     grep -En '[A-Z][a-z]+[A-Z][a-z]+\.(go|py|ts|rs)' "$file" 2>/dev/null
     grep -En '\./[a-z]+/' "$file" 2>/dev/null
     ```
     If matches: WARN user with matched lines, ask to proceed or revise. Never block the write.

**Note:** Each learning goes to ONE location (local or global). No `promoted_to` needed — there's no local copy to mark when `/retro` writes directly to global.

**Example abstraction:**
- Local: "Athena's validate package needs O_CREATE|O_EXCL for atomic claims because Zeus spawns concurrent workers"
- Global: "Use O_CREATE|O_EXCL for atomic file creation when multiple processes may race on the same path"
### Step 5.6: Compile Constraint Templates

For each extracted learning scoring >= 4/5 on actionability AND tagged "constraint" or "anti-pattern", run `bash hooks/constraint-compiler.sh <learning-path>` to generate a constraint template.

```bash
# Compile high-scoring constraint/anti-pattern learnings into enforcement templates
for f in .agents/learnings/YYYY-MM-DD-*.md; do
    [ -f "$f" ] || continue
    bash hooks/constraint-compiler.sh "$f" 2>/dev/null || true
done
```

This produces draft constraint templates in `.agents/constraints/` that can later be activated via `ao constraint activate <id>`.

### Step 6: Write Retro Summary

**Write to:** `.agents/retros/YYYY-MM-DD-<topic>.md`

```markdown
---
id: retro-YYYY-MM-DD-<topic-slug>
type: retro
date: YYYY-MM-DD
---

# Retrospective: <Topic>

**Scope:** <what work was reviewed>

## Summary
<1-2 sentence overview>

## What Went Well
- <thing 1>
- <thing 2>

## What Could Be Improved
- <improvement 1>
- <improvement 2>

## Learnings Extracted
- L1: <brief>
- L2: <brief>

See: `.agents/learnings/YYYY-MM-DD-<topic>.md`

## Proactive Improvement Agenda

| # | Area | Improvement | Priority | Horizon | Effort | Evidence |
|---|------|-------------|----------|---------|--------|----------|
| 1 | repo / execution / CI | <improvement> | P0/P1/P2 | now/next-cycle/later | S/M/L | <retro evidence> |

### Recommended Next /rpi
/rpi "<highest-value item>"

## Action Items
- [ ] <any follow-up needed>
```

### Step 6.5: Proactive Improvement Agenda (MANDATORY)

After writing the retro summary, use the full context you just gathered to propose concrete improvements.

Ask explicitly:
1. **Repo:** What should we improve in the codebase/contracts/docs to reduce future defects?
2. **Execution:** What should we improve in planning/implementation/review workflow to increase throughput?
3. **CI/Automation:** What should we improve in validation gates/tooling to reduce noise and catch regressions earlier?

Requirements:
- Propose at least **5** items total.
- Cover all three areas above (repo, execution, CI/automation).
- Include at least **1 quick win** (small, low-risk, same-session viable).
- For each item include: `priority` (P0/P1/P2), `horizon` (now/next-cycle/later), `effort` (S/M/L), and one-line rationale tied to retro evidence.
- Mark one item as **Recommended Next /rpi**.

Write this into the retro file under:
```markdown
## Proactive Improvement Agenda

| # | Area | Improvement | Priority | Horizon | Effort | Evidence |
|---|------|-------------|----------|---------|--------|----------|
| 1 | CI | <improvement> | P0 | now | S | <retro evidence> |

### Recommended Next /rpi
/rpi "<highest-value item>"
```

### Step 7: Feed the Knowledge Flywheel (auto-extract)

```bash
# If ao available, index via forge, close session, and trigger flywheel
if command -v ao &>/dev/null; then
  ao forge markdown .agents/learnings/YYYY-MM-DD-*.md 2>/dev/null
  echo "Learnings indexed in knowledge flywheel"

  # Apply feedback from completed tasks to associated learnings
  ao task-feedback 2>/dev/null
  echo "Task feedback applied"

  # Close session and trigger full flywheel close-loop
  ao session close 2>/dev/null || true
  ao flywheel close-loop --quiet 2>/dev/null || true
  echo "Session closed, flywheel loop triggered"

  # Sync insights to MEMORY.md immediately (don't wait for session end)
  ao notebook update --quiet 2>/dev/null || true

  # Flag stale constraints for retirement
  ao constraint review 2>/dev/null || true
else
  # Learnings are already written to .agents/learnings/ by Step 5.
  # Without ao CLI, grep-based search in /research and /inject
  # will find them directly — no copy to pending needed.

  # Build lightweight keyword index for faster search
  mkdir -p .agents/ao
  for f in .agents/learnings/YYYY-MM-DD-*.md; do
    [ -f "$f" ] || continue
    TITLE=$(head -1 "$f" | sed 's/^# //')
    echo "{\"file\": \"$f\", \"title\": \"$TITLE\", \"keywords\": [], \"timestamp\": \"$(date -Iseconds)\"}" >> .agents/ao/search-index.jsonl
  done
  echo "Learnings indexed locally (ao CLI not available — grep-based search active)"
fi
```

This auto-extraction step ensures every retro feeds the flywheel without requiring the user to remember manual commands.

### Step 8: Report to User

Tell the user:
1. Number of learnings extracted
2. Key insights (top 2-3)
3. Location of retro and learnings files
4. Knowledge has been indexed for future sessions
5. Top proactive improvements (top 3) + recommended next `/rpi`

## Key Rules

- **Be specific** - "auth tokens expire" not "learned about auth"
- **Be actionable** - learnings should inform future decisions
- **Cite sources** - reference what work the learning came from
- **Write both files** - retro summary AND detailed learnings
- **Be proactive** - always produce repo + execution + CI improvements from gathered context
- **Index knowledge** - make it discoverable

## The Flywheel

Learnings feed future research:
```
Work → /retro → improvements + learnings → ao forge markdown → /research finds it
```

Future sessions start smarter because of your retrospective.

## Examples

### Retrospective After Implementation

**User says:** `/retro`

**What happens:**
1. Agent looks at recent activity via `git log --oneline -10`
2. Agent finds 8 commits related to authentication refactor
3. Agent reads commit messages, code changes, and related issue in beads
4. Agent asks: What went well? What went wrong? What was discovered?
5. Agent identifies 4 learnings: L1 (token expiry pattern), L2 (middleware ordering matters), L3 (test coverage caught edge case), L4 (documentation prevents support load)
6. Agent writes learnings file to `.agents/learnings/2026-02-13-auth-refactor.md`
7. Agent writes retro summary to `.agents/retros/2026-02-13-auth-refactor.md`
8. Agent runs `ao forge markdown` to add learnings to knowledge base

**Result:** 4 learnings extracted and indexed, retro summary documents what went well and improvements needed.

### Post-Mortem with Vibe Results

**User says:** `/retro --vibe-results .agents/council/2026-02-13-vibe-api.md`

**What happens:**
1. Agent reads vibe results file showing 2 CRITICAL and 3 HIGH findings
2. Agent extracts learnings from validation findings (race condition pattern, missing input validation)
3. Agent reviews recent commits for context
4. Agent creates 6 learnings: 2 from vibe findings (what to avoid), 4 from successful patterns (what to repeat)
5. Agent writes both learnings and retro files
6. Agent indexes knowledge automatically via ao forge

**Result:** Vibe findings incorporated into learnings, preventing same issues in future work.

## Troubleshooting

| Problem | Cause | Solution |
|---------|-------|----------|
| No recent activity found | Clean git history or work not committed yet | Ask user what to retrospect. Accept manual topic: `/retro "planning process improvements"`. Review uncommitted changes if needed. |
| Learnings too generic | Insufficient analysis or surface-level review | Dig deeper into code changes. Ask "why" repeatedly. Ensure learnings are actionable (specific pattern, not vague principle). Check confidence level. |
| ao forge markdown fails | ao CLI not installed or .agents/ structure wrong | Graceful fallback: index learnings locally to `.agents/ao/search-index.jsonl`. Notify user ao not available. Learnings still in `.agents/learnings/` and discoverable via grep-based search. |
| Duplicate learnings extracted | Same insight from multiple sources | Deduplicate before writing. Check existing learnings with grep. Merge duplicates into single learning with multiple source citations. |

## Reference Documents

- [references/context-gathering.md](references/context-gathering.md)
- [references/output-templates.md](references/output-templates.md)