diff --git a/commands/retro.md b/commands/retro.md index e4fb89c..267d757 100644 --- a/commands/retro.md +++ b/commands/retro.md @@ -5,9 +5,10 @@ argument-hint: [task-description] # Retrospective -Capture learnings from completed AI-assisted work to improve the workflow and refine the product vision. +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 @@ -18,75 +19,108 @@ 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 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. **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. **Store the learning**: Create a learning file in the architecture repo: - If any vision updates are needed: - - Present suggested changes to `vision.md` + **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 vision file and sync to Gitea + - Update the appropriate file -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: +## Encoding Destinations -```bash -tea issues create -r flowmade-one/ai --title "" --description "<body>" --milestone "<milestone>" -``` +| 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) | -## Milestone Assignment +## Architecture vs Product Repos -Before creating issues, fetch available milestones: +**In the architecture repo**: +- Learning files are created directly in `learnings/` +- Issues are created in the same repo +- Vision changes affect `manifesto.md` -```bash -tea milestones -f title,description -``` - -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 - -## Issue Format - -Use this structure for retrospective issues: - -```markdown -## Context -What task triggered this learning (brief). - -## Problem / Observation -What was the friction point or insight. - -## Suggested Improvement -Concrete, actionable change to make. - -## Affected Files -- commands/xxx.md -- skills/xxx/SKILL.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: -- `retrospective` - Always add this +Add appropriate labels to encoding 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 +- **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