Simplify /retro flow: issue first, encoding later

Changed the retro flow to: 1. Retro (any repo) → Issue (architecture repo) 2. Later: Encode issue into learning file + skill/command/agent Key changes: - Retro now only creates issues, not learning files - Learning files are created when the issue is worked on - All issues go to architecture repo regardless of source repo - Added "When the Issue is Worked On" section for encoding guidance - Clearer separation between capturing insights and encoding them 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Update /retro command to store learnings and create encoding issues
2026-01-07 20:38:29 +01:00 · 2026-01-07 20:27:29 +01:00
1 changed files with 76 additions and 52 deletions
--- a/commands/retro.md
+++ b/commands/retro.md
@@ -1,13 +1,22 @@
 ---
-description: Run a retrospective on completed work. Captures learnings, creates improvement issues, and updates product vision.
+description: Run a retrospective on completed work. Captures insights as issues for later encoding into skills/commands/agents.
 argument-hint: [task-description]
 ---
 # Retrospective
-Capture learnings from completed AI-assisted work to improve the workflow and refine the product vision.
+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
@@ -18,75 +27,90 @@ Capture learnings from completed AI-assisted work to improve the workflow and re
   - What worked well?
   - Any specific improvement ideas?
-3. **Analyze and categorize**: Group learnings into:
+3. **Identify insights**: For each insight, determine:
-   - **Prompt improvements**: Better instructions for commands/skills
+   - **What was learned**: The specific insight
-   - **Missing capabilities**: New commands or skills needed
+   - **Where to encode it**: Which skill, command, or agent should change?
-   - **Tool issues**: Problems with tea CLI, git, or other tools
+   - **Governance impact**: What does this mean for how we work?
   - **Context gaps**: Missing documentation or skills
-4. **Connect to vision** (if `vision.md` exists in the target repo):
+4. **Create issue on architecture repo**: Always create issues on `flowmade-one/ai`:
   - Did this work make progress on any vision goals?
   - Did learnings reveal new priorities that should become goals?
   - Did we discover something that should be a non-goal?
   - Should the current focus shift based on what we learned?
   If any vision updates are needed:
   - Present suggested changes to `vision.md`
   - Ask for approval
   - Update the vision file and sync to Gitea
 5. **Generate improvement issues**: For each actionable improvement:
   - Determine the appropriate milestone (see Milestone Categorization below)
   - Create an issue in the AI repo with the milestone assigned:
   ```bash
-tea issues create -r flowmade-one/ai --title "<title>" --description "<body>" --milestone "<milestone>"
+   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]"
   ```
-## Milestone Assignment
+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)
-Before creating issues, fetch available milestones:
+   If vision updates are needed, present suggested changes and ask for approval.
-```bash
+## When the Issue is Worked On
 tea milestones -f title,description
 ```
-For each issue, automatically assign to the most relevant milestone by matching:
+When encoding a learning issue, the implementer should:
 - Issue content/problem area → Milestone title and description
 - If no clear match, ask the user which milestone (goal) the issue supports
 - If no milestones exist, skip milestone assignment
-## Issue Format
+1. **Create learning file**: `learnings/YYYY-MM-DD-short-title.md`
 Use this structure for retrospective issues:
   ```markdown
-## Context
+   # [Learning Title]
 What task triggered this learning (brief).
-## Problem / Observation
+   **Date**: YYYY-MM-DD
-What was the friction point or insight.
+   **Context**: [Task that triggered this learning]
   **Issue**: #XX
-## Suggested Improvement
+   ## Learning
 Concrete, actionable change to make.
-## Affected Files
+   [The specific insight]
- commands/xxx.md
+
- skills/xxx/SKILL.md
+   ## 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:
+Add appropriate labels to issues:
- `retrospective` - Always add this
+- `learning` - Always add this
 - `prompt-improvement` - For command/skill text changes
- `new-feature` - For new commands/skills
+- `new-feature` - For new commands/skills/agents
 - `bug` - For things that are broken
 ## Guidelines
- Be specific and actionable - vague issues won't get fixed
+- **Always create issues on architecture repo** - regardless of which repo the retro runs in
- One issue per improvement (don't bundle unrelated things)
+- **Be specific**: Vague insights can't be encoded
- Reference specific commands/skills when relevant
+- **One issue per insight**: Don't bundle unrelated things
- Keep issues small and focused
+- **Encoding happens later**: Retro captures the issue, encoding is separate work
- Skip creating issues for one-off edge cases that won't recur
+- **Skip one-offs**: Don't capture insights for edge cases that won't recur