flowmade-one/architecture
3
0
Fork 0
Code Issues 15 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Simplify /retro flow: issue first, encoding later

Browse Source 
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>
This commit was merged in pull request #50.
This commit is contained in:
Hugo Nijhuis
2026-01-07 20:38:29 +01:00
parent 8868eedc31
commit fac88cfcc7
1 changed files with 56 additions and 66 deletions
Download Patch File Download Diff File Expand all files Collapse all files

122
commands/retro.md
View File

@@ -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] <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`
```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