architecture/commands/retro.md

description, argument-hint

description	argument-hint
Run a retrospective on completed work. Captures insights as issues for later encoding into skills/commands/agents.	task-description

Retrospective

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.

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 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. Create issue on architecture repo: Always create issues on flowmade-one/architecture:

   tea issues create -r flowmade-one/architecture \
     --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]"
   

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

   # [Learning Title]
   
   **Date**: YYYY-MM-DD
   **Context**: [Task that triggered this learning]
   **Issue**: #XX
   
   ## Learning
   
   [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 to 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

• 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