architecture/commands/retro.md

description, argument-hint

description	argument-hint
Run a retrospective on completed work. Captures learnings, creates improvement issues, and updates product vision.	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.

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

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 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. Store the learning: Create a learning file in the architecture repo:

   File: learnings/YYYY-MM-DD-short-title.md

   # [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]
   

   # 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:

   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

Encoding Destinations

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)

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:

• 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

• 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