---
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