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:
-   - **Prompt improvements**: Better instructions for commands/skills
-   - **Missing capabilities**: New commands or skills needed
-   - **Tool issues**: Problems with tea CLI, git, or other tools
-   - **Context gaps**: Missing documentation or skills
+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. **Connect to vision** (if `vision.md` exists in the target repo):
-   - 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?
+4. **Create issue on architecture repo**: Always create issues on `flowmade-one/ai`:

-   If any vision updates are needed:
-   - Present suggested changes to `vision.md`
-   - Ask for approval
-   - Update the vision file and sync to Gitea
+   ```bash
+   tea issues create -r flowmade-one/ai \
+     --title "[Learning] <brief description>" \
+     --description "## Context
+   [Task that triggered this insight]

-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:
+   ## Insight
+   [The specific learning - be concrete and actionable]

-```bash
-tea issues create -r flowmade-one/ai --title "<title>" --description "<body>" --milestone "<milestone>"
-```
+   ## 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]

-## Milestone Assignment
+   ## Governance
+   [What this means for how we work going forward]"
+   ```

-Before creating issues, fetch available milestones:
+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)

-```bash
-tea milestones -f title,description
-```
+   If vision updates are needed, present suggested changes and ask for approval.

-For each issue, automatically assign to the most relevant milestone by matching:
- 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
+## When the Issue is Worked On

-## Issue Format
+When encoding a learning issue, the implementer should:

-Use this structure for retrospective issues:
+1. **Create learning file**: `learnings/YYYY-MM-DD-short-title.md`

-```markdown
-## Context
-What task triggered this learning (brief).
+   ```markdown
+   # [Learning Title]

-## Problem / Observation
-What was the friction point or insight.
+   **Date**: YYYY-MM-DD
+   **Context**: [Task that triggered this learning]
+   **Issue**: #XX

-## Suggested Improvement
-Concrete, actionable change to make.
+   ## Learning

-## Affected Files
- commands/xxx.md
- skills/xxx/SKILL.md
-```
+   [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:
- `retrospective` - Always add this
+Add appropriate labels to issues:
+- `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
- One issue per improvement (don't bundle unrelated things)
- Reference specific commands/skills when relevant
- Keep issues small and focused
- Skip creating issues for one-off edge cases that won't recur
+- **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