---
description: Run a retrospective on completed work. Captures insights as issues for later encoding into skills/commands/agents.
argument-hint: [task-description]
---

# Retrospective

Capture insights from completed work as issues on the architecture repo. Issues are later encoded into learnings and skills/commands/agents.

@~/.claude/skills/vision-management/SKILL.md
@~/.claude/skills/gitea/SKILL.md

## Flow

```
Retro (any repo) → Issue (architecture repo) → Encode: learning file + skill/command/agent
```

The retro creates the issue. Encoding happens when the issue is worked on.

## 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 insights**: 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. **Create issue on architecture repo**: Always create issues on `flowmade-one/ai`:

   ```bash
   tea issues create -r flowmade-one/ai \
     --title "[Learning] <brief description>" \
     --description "## Context
   [Task that triggered this insight]

   ## Insight
   [The specific learning - be concrete and actionable]

   ## Suggested Encoding
   - [ ] \`skills/xxx/SKILL.md\` - [what to add/change]
   - [ ] \`commands/xxx.md\` - [what to add/change]
   - [ ] \`agents/xxx/agent.md\` - [what to add/change]

   ## Governance
   [What this means for how we work going forward]"
   ```

5. **Connect to vision**: Check if insight 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 and ask for approval.

## When the Issue is Worked On

When encoding a learning issue, the implementer should:

1. **Create learning file**: `learnings/YYYY-MM-DD-short-title.md`

   ```markdown
   # [Learning Title]

   **Date**: YYYY-MM-DD
   **Context**: [Task that triggered this learning]
   **Issue**: #XX

   ## Learning

   [The specific insight]

   ## Encoded In

   - `skills/xxx/SKILL.md` - [what was added/changed]
   - `commands/xxx.md` - [what was added/changed]

   ## Governance

   [What this means for how we work]
   ```

2. **Update skill/command/agent** with the encoded knowledge

3. **Close the issue** with reference to the learning file and changes made

## Encoding Destinations

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

## Labels

Add appropriate labels to 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

- **Always create issues on architecture repo** - regardless of which repo the retro runs in
- **Be specific**: Vague insights can't be encoded
- **One issue per insight**: Don't bundle unrelated things
- **Encoding happens later**: Retro captures the issue, encoding is separate work
- **Skip one-offs**: Don't capture insights for edge cases that won't recur