Compare commits
3 Commits
issue-40-m
...
fix-retro-
| Author | SHA1 | Date | |
|---|---|---|---|
fac88cfcc7
|
|||
|
8868eedc31
|
|||
|
c0ef16035c
|
@@ -1,13 +1,22 @@
|
||||
---
|
||||
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 AI-assisted work to improve the workflow and refine the product vision.
|
||||
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
|
||||
|
||||
@@ -18,75 +27,90 @@ 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 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. **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. **Create issue on architecture repo**: Always create issues on `flowmade-one/ai`:
|
||||
|
||||
If any vision updates are needed:
|
||||
- Present suggested changes to `vision.md`
|
||||
- Ask for approval
|
||||
- Update the vision file and sync to Gitea
|
||||
```bash
|
||||
tea issues create -r flowmade-one/ai \
|
||||
--title "[Learning] <brief description>" \
|
||||
--description "## Context
|
||||
[Task that triggered this insight]
|
||||
|
||||
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:
|
||||
## Insight
|
||||
[The specific learning - be concrete and actionable]
|
||||
|
||||
```bash
|
||||
tea issues create -r flowmade-one/ai --title "<title>" --description "<body>" --milestone "<milestone>"
|
||||
```
|
||||
## 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]
|
||||
|
||||
## Milestone Assignment
|
||||
## Governance
|
||||
[What this means for how we work going forward]"
|
||||
```
|
||||
|
||||
Before creating issues, fetch available milestones:
|
||||
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)
|
||||
|
||||
```bash
|
||||
tea milestones -f title,description
|
||||
```
|
||||
If vision updates are needed, present suggested changes and ask for approval.
|
||||
|
||||
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
|
||||
## When the Issue is Worked On
|
||||
|
||||
## Issue Format
|
||||
When encoding a learning issue, the implementer should:
|
||||
|
||||
Use this structure for retrospective issues:
|
||||
1. **Create learning file**: `learnings/YYYY-MM-DD-short-title.md`
|
||||
|
||||
```markdown
|
||||
## Context
|
||||
What task triggered this learning (brief).
|
||||
```markdown
|
||||
# [Learning Title]
|
||||
|
||||
## Problem / Observation
|
||||
What was the friction point or insight.
|
||||
**Date**: YYYY-MM-DD
|
||||
**Context**: [Task that triggered this learning]
|
||||
**Issue**: #XX
|
||||
|
||||
## Suggested Improvement
|
||||
Concrete, actionable change to make.
|
||||
## Learning
|
||||
|
||||
## Affected Files
|
||||
- commands/xxx.md
|
||||
- skills/xxx/SKILL.md
|
||||
```
|
||||
[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:
|
||||
- `retrospective` - Always add this
|
||||
Add appropriate labels to 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
|
||||
- **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
|
||||
|
||||
@@ -8,47 +8,54 @@ argument-hint: [goals]
|
||||
@~/.claude/skills/vision-management/SKILL.md
|
||||
@~/.claude/skills/gitea/SKILL.md
|
||||
|
||||
This command manages **product-level** vision. For organization-level vision, use `/manifesto`.
|
||||
|
||||
## Architecture
|
||||
|
||||
The vision system has two layers:
|
||||
| Level | Document | Purpose | Command |
|
||||
|-------|----------|---------|---------|
|
||||
| **Organization** | `manifesto.md` | Who we are, shared personas, beliefs | `/manifesto` |
|
||||
| **Product** | `vision.md` | Product-specific personas, jobs, solution | `/vision` |
|
||||
| **Goals** | Gitea milestones | Measurable progress toward vision | `/vision goals` |
|
||||
|
||||
| Layer | Purpose | Location |
|
||||
|-------|---------|----------|
|
||||
| **vision.md** | North star philosophy (why, principles, non-goals) | File in repo root |
|
||||
| **Milestones** | Goals with progress tracking | Gitea milestones |
|
||||
|
||||
Issues are assigned to milestones. Progress is visible through milestone completion.
|
||||
Product vision inherits from and extends the organization manifesto.
|
||||
|
||||
## Process
|
||||
|
||||
1. **Check for existing vision**: Look for `vision.md` in the current repo root.
|
||||
1. **Check for organization manifesto**: Note if `manifesto.md` exists (provides org context)
|
||||
|
||||
2. **If no vision exists**:
|
||||
- Ask the user if they want to create one
|
||||
2. **Check for product vision**: Look for `vision.md` in the current repo root
|
||||
|
||||
3. **If no vision exists**:
|
||||
- Reference the organization manifesto if it exists
|
||||
- Ask if the user wants to create a product vision
|
||||
- Guide them through defining:
|
||||
1. **Personas**: Who are we building for? (2-4 specific personas)
|
||||
2. **Jobs to be done**: What are they trying to achieve?
|
||||
3. **The problem**: What pain points exist today?
|
||||
4. **The solution**: How does this product address their jobs?
|
||||
5. **Guiding principles**: What beliefs guide decisions?
|
||||
6. **Non-goals**: What are we explicitly NOT doing?
|
||||
- Create `vision.md` (do NOT include goals/progress - that's milestones)
|
||||
- Ask about initial goals tied to personas/jobs, create as Gitea milestones
|
||||
1. **Product personas**: Who does this product serve? (may extend org personas)
|
||||
2. **Product jobs**: What specific jobs does this product address?
|
||||
3. **The problem**: What pain points does this product solve?
|
||||
4. **The solution**: How does this product address those jobs?
|
||||
5. **Product principles**: Any product-specific principles (beyond org principles)?
|
||||
6. **Product non-goals**: What is this product explicitly NOT doing?
|
||||
- Create `vision.md`
|
||||
- Ask about initial goals, create as Gitea milestones
|
||||
|
||||
3. **If vision exists**:
|
||||
- Display the vision philosophy from `vision.md`
|
||||
4. **If vision exists**:
|
||||
- Display organization context (if manifesto exists)
|
||||
- Display the product vision from `vision.md`
|
||||
- Show current milestones and their progress: `tea milestones`
|
||||
- Check if `$1` specifies an action:
|
||||
- `goals`: Manage milestones (add, close, view progress)
|
||||
- If no action specified, just display the current state
|
||||
|
||||
4. **Managing Goals (milestones)**:
|
||||
5. **Managing Goals (milestones)**:
|
||||
```bash
|
||||
# List milestones with progress
|
||||
tea milestones
|
||||
|
||||
# Create a new goal
|
||||
tea milestones create --title "<goal>" --description "<success criteria>"
|
||||
tea milestones create --title "<goal>" --description "For: <persona>
|
||||
Job: <job to be done>
|
||||
Success: <criteria>"
|
||||
|
||||
# View issues in a milestone
|
||||
tea milestones issues <milestone-name>
|
||||
@@ -60,37 +67,44 @@ Issues are assigned to milestones. Progress is visible through milestone complet
|
||||
## Output Format
|
||||
|
||||
```
|
||||
## Who We Serve
|
||||
## Organization Context
|
||||
|
||||
- **[Persona 1]**: [Brief description]
|
||||
- **[Persona 2]**: [Brief description]
|
||||
See manifesto for shared personas, beliefs, and principles.
|
||||
[Link or note about manifesto.md location]
|
||||
|
||||
## What They're Trying to Achieve
|
||||
## Product: [Name]
|
||||
|
||||
- "[Job to be done 1]"
|
||||
- "[Job to be done 2]"
|
||||
### Who This Product Serves
|
||||
|
||||
## Vision
|
||||
- **[Persona 1]**: [Product-specific description]
|
||||
- **[Persona 2]**: [Product-specific description]
|
||||
|
||||
### What They're Trying to Achieve
|
||||
|
||||
- "[Product-specific job 1]"
|
||||
- "[Product-specific job 2]"
|
||||
|
||||
### Product Vision
|
||||
|
||||
[Summary of problem/solution from vision.md]
|
||||
|
||||
## Goals (Milestones)
|
||||
### Goals (Milestones)
|
||||
|
||||
| Goal | For | Progress | Due |
|
||||
|------|-----|----------|-----|
|
||||
| [title] | [Persona] | 3/5 issues | [date] |
|
||||
|
||||
## Current Focus
|
||||
### Current Focus
|
||||
|
||||
[Open milestones with nearest due dates or most activity]
|
||||
```
|
||||
|
||||
## Guidelines
|
||||
|
||||
- vision.md is the stable "why" and "who" document - update rarely
|
||||
- Personas and jobs to be done are foundational - everything traces back to them
|
||||
- Milestones are actionable goals - each should serve a specific persona's job
|
||||
- Assign issues to milestones to track progress
|
||||
- Use milestone descriptions for: persona, job, success criteria
|
||||
- Due dates on milestones are optional but help prioritization
|
||||
- If you can't tie work to a persona/job, question whether it should be done
|
||||
- Product vision builds on organization manifesto - don't duplicate, extend
|
||||
- Product personas can be more specific versions of org personas
|
||||
- Product jobs should trace back to org-level jobs to be done
|
||||
- Milestones are product-specific goals toward the vision
|
||||
- Use `/manifesto` for organization-level identity and beliefs
|
||||
- Use `/vision` for product-specific direction and goals
|
||||
- If this is the architecture repo itself, use `/manifesto` instead
|
||||
|
||||
Reference in New Issue
Block a user