Retro Skill
YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.
Extract learnings from completed work and feed the knowledge flywheel.
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
# Learning: <Short Title>
**ID**: L1
**Category**: <category>
**Confidence**: <high|medium|low>
## 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 6: Write Retro Summary
Write to: .agents/retros/YYYY-MM-DD-<topic>.md
markdown
# Retrospective: <Topic>
**Date:** YYYY-MM-DD
**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`
## Action Items
- [ ] <any follow-up needed>
Step 7: Feed the Knowledge Flywheel (auto-extract)
bash
mkdir -p .agents/knowledge/pending
# If ao available, index via forge
if command -v ao &>/dev/null; then
ao forge index .agents/learnings/YYYY-MM-DD-*.md 2>/dev/null
echo "Learnings indexed in knowledge flywheel"
else
# Fallback: copy learnings to pending for future import
cp .agents/learnings/YYYY-MM-DD-*.md .agents/knowledge/pending/ 2>/dev/null
echo "Note: ao CLI not installed. Learnings saved to .agents/knowledge/pending/"
echo "Install ao to enable automatic knowledge flywheel."
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:
- Number of learnings extracted
- Key insights (top 2-3)
- Location of retro and learnings files
- Knowledge has been indexed for future sessions
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
- Index knowledge - make it discoverable
The Flywheel
Learnings feed future research:
Work → /retro → .agents/learnings/ → ao forge index → /research finds it
Future sessions start smarter because of your retrospective.