From fac88cfcc76491a46b606544e002deff7661bc84 Mon Sep 17 00:00:00 2001 From: Hugo Nijhuis Date: Wed, 7 Jan 2026 20:38:29 +0100 Subject: [PATCH] Simplify /retro flow: issue first, encoding later MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- commands/retro.md | 122 +++++++++++++++++++++------------------------- 1 file changed, 56 insertions(+), 66 deletions(-) diff --git a/commands/retro.md b/commands/retro.md index 267d757..71dcc53 100644 --- a/commands/retro.md +++ b/commands/retro.md @@ -1,15 +1,23 @@ --- -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 work. Learnings are stored for historical record and governance, then encoded into skills/commands/agents where Claude can use them. +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. @@ -19,99 +27,81 @@ Capture learnings from completed work. Learnings are stored for historical recor - What worked well? - Any specific improvement ideas? -3. **Identify learnings**: For each insight, determine: +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. **Store the learning**: Create a learning file in the architecture repo: +4. **Create issue on architecture repo**: Always create issues on `flowmade-one/ai`: - **File**: `learnings/YYYY-MM-DD-short-title.md` + ```bash + tea issues create -r flowmade-one/ai \ + --title "[Learning] " \ + --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 - be concrete and actionable] + [The specific insight] ## Encoded In - - Pending: Issue #XX to update [target skill/command/agent] + - `skills/xxx/SKILL.md` - [what was added/changed] + - `commands/xxx.md` - [what was added/changed] ## Governance - [What this means for how we work going forward] + [What this means for how we work] ``` - ```bash - # Create the learning file in architecture repo - # If in architecture repo: - cat > learnings/YYYY-MM-DD-short-title.md << 'EOF' - [content] - EOF +2. **Update skill/command/agent** with the encoded knowledge - # 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 +3. **Close the issue** with reference to the learning file and changes made ## Encoding Destinations -| Learning Type | Encode In | -|---------------|-----------| +| 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) | -## 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: +Add appropriate labels to issues: - `learning` - Always add this - `prompt-improvement` - For command/skill text changes - `new-feature` - For new commands/skills/agents @@ -119,8 +109,8 @@ Add appropriate labels to encoding issues: ## 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 +- **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