Hugo Nijhuis
8868eedc31
Restructured retro flow to: 1. Store learnings in learnings/ folder (historical + governance) 2. Create encoding issues to update skills/commands/agents 3. Cross-reference between learning files and issues 4. Handle both architecture and product repos differently Key changes: - Learning file template with Date, Context, Learning, Encoded In, Governance - Encoding issue template referencing the learning file - Encoding destinations table (skill/command/agent/manifesto/vision) - Clear guidance for architecture vs product repo workflows - Updated labels (learning instead of retrospective) Closes #42 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
127 lines
3.9 KiB
Markdown
127 lines
3.9 KiB
Markdown
---
|
|
description: Run a retrospective on completed work. Captures learnings, creates improvement issues, and updates product vision.
|
|
argument-hint: [task-description]
|
|
---
|
|
|
|
# Retrospective
|
|
|
|
Capture learnings from completed work. Learnings are stored for historical record and governance, then encoded into skills/commands/agents where Claude can use them.
|
|
|
|
@~/.claude/skills/vision-management/SKILL.md
|
|
@~/.claude/skills/gitea/SKILL.md
|
|
|
|
## Process
|
|
|
|
1. **Gather context**: If $1 is provided, use it as the task description. Otherwise, ask the user what task was just completed.
|
|
|
|
2. **Reflect on the work**: Ask the user (or summarize from conversation context if obvious):
|
|
- What friction points were encountered?
|
|
- What worked well?
|
|
- Any specific improvement ideas?
|
|
|
|
3. **Identify learnings**: For each insight, determine:
|
|
- **What was learned**: The specific insight
|
|
- **Where to encode it**: Which skill, command, or agent should change?
|
|
- **Governance impact**: What does this mean for how we work?
|
|
|
|
4. **Store the learning**: Create a learning file in the architecture repo:
|
|
|
|
**File**: `learnings/YYYY-MM-DD-short-title.md`
|
|
|
|
```markdown
|
|
# [Learning Title]
|
|
|
|
**Date**: YYYY-MM-DD
|
|
**Context**: [Task that triggered this learning]
|
|
|
|
## Learning
|
|
|
|
[The specific insight - be concrete and actionable]
|
|
|
|
## Encoded In
|
|
|
|
- Pending: Issue #XX to update [target skill/command/agent]
|
|
|
|
## Governance
|
|
|
|
[What this means for how we work going forward]
|
|
```
|
|
|
|
```bash
|
|
# Create the learning file in architecture repo
|
|
# If in architecture repo:
|
|
cat > learnings/YYYY-MM-DD-short-title.md << 'EOF'
|
|
[content]
|
|
EOF
|
|
|
|
# If in a different repo, note that learning should be added to architecture repo
|
|
```
|
|
|
|
5. **Create encoding issue**: Create an issue to encode the learning:
|
|
|
|
```bash
|
|
tea issues create -r flowmade-one/ai \
|
|
--title "Encode learning: [brief description]" \
|
|
--description "## Learning Reference
|
|
See: learnings/YYYY-MM-DD-short-title.md
|
|
|
|
## What to Encode
|
|
[The specific change to make]
|
|
|
|
## Target
|
|
- [ ] \`skills/xxx/SKILL.md\` - [what to add/change]
|
|
- [ ] \`commands/xxx.md\` - [what to add/change]
|
|
|
|
## Governance
|
|
[Why this matters]"
|
|
```
|
|
|
|
6. **Update learning file**: Add the issue reference to the "Encoded In" section.
|
|
|
|
7. **Connect to vision**: Check if learning affects vision:
|
|
- **Architecture repo**: Does this affect `manifesto.md`? (beliefs, principles, non-goals)
|
|
- **Product repo**: Does this affect `vision.md`? (product direction, goals)
|
|
|
|
If vision updates are needed:
|
|
- Present suggested changes
|
|
- Ask for approval
|
|
- Update the appropriate file
|
|
|
|
## Encoding Destinations
|
|
|
|
| Learning Type | Encode In |
|
|
|---------------|-----------|
|
|
| How to use a tool | `skills/[tool]/SKILL.md` |
|
|
| Workflow improvement | `commands/[command].md` |
|
|
| Subtask behavior | `agents/[agent]/agent.md` |
|
|
| Organization belief | `manifesto.md` |
|
|
| Product direction | `vision.md` (in product repo) |
|
|
|
|
## Architecture vs Product Repos
|
|
|
|
**In the architecture repo**:
|
|
- Learning files are created directly in `learnings/`
|
|
- Issues are created in the same repo
|
|
- Vision changes affect `manifesto.md`
|
|
|
|
**In product repos**:
|
|
- Learning files should be added to the architecture repo (not the product repo)
|
|
- Issues are created in `flowmade-one/ai` (architecture repo)
|
|
- Local vision changes affect `vision.md` in the product repo
|
|
|
|
## Labels
|
|
|
|
Add appropriate labels to encoding issues:
|
|
- `learning` - Always add this
|
|
- `prompt-improvement` - For command/skill text changes
|
|
- `new-feature` - For new commands/skills/agents
|
|
- `bug` - For things that are broken
|
|
|
|
## Guidelines
|
|
|
|
- **Be specific**: Vague learnings can't be encoded
|
|
- **One learning per file**: Don't bundle unrelated insights
|
|
- **Always encode**: A learning without encoding is just documentation
|
|
- **Reference both ways**: Learning file → Issue, Issue → Learning file
|
|
- **Skip one-offs**: Don't capture learnings for edge cases that won't recur
|