Compare commits
4 Commits
issue-40-m
...
issue-43-v
| Author | SHA1 | Date | |
|---|---|---|---|
dc7b554ee6
|
|||
|
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]
|
argument-hint: [task-description]
|
||||||
---
|
---
|
||||||
|
|
||||||
# Retrospective
|
# 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/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
|
## Process
|
||||||
|
|
||||||
@@ -18,75 +27,90 @@ Capture learnings from completed AI-assisted work to improve the workflow and re
|
|||||||
- What worked well?
|
- What worked well?
|
||||||
- Any specific improvement ideas?
|
- Any specific improvement ideas?
|
||||||
|
|
||||||
3. **Analyze and categorize**: Group learnings into:
|
3. **Identify insights**: For each insight, determine:
|
||||||
- **Prompt improvements**: Better instructions for commands/skills
|
- **What was learned**: The specific insight
|
||||||
- **Missing capabilities**: New commands or skills needed
|
- **Where to encode it**: Which skill, command, or agent should change?
|
||||||
- **Tool issues**: Problems with tea CLI, git, or other tools
|
- **Governance impact**: What does this mean for how we work?
|
||||||
- **Context gaps**: Missing documentation or skills
|
|
||||||
|
|
||||||
4. **Connect to vision** (if `vision.md` exists in the target repo):
|
4. **Create issue on architecture repo**: Always create issues on `flowmade-one/ai`:
|
||||||
- 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?
|
|
||||||
|
|
||||||
If any vision updates are needed:
|
```bash
|
||||||
- Present suggested changes to `vision.md`
|
tea issues create -r flowmade-one/ai \
|
||||||
- Ask for approval
|
--title "[Learning] <brief description>" \
|
||||||
- Update the vision file and sync to Gitea
|
--description "## Context
|
||||||
|
[Task that triggered this insight]
|
||||||
|
|
||||||
5. **Generate improvement issues**: For each actionable improvement:
|
## Insight
|
||||||
- Determine the appropriate milestone (see Milestone Categorization below)
|
[The specific learning - be concrete and actionable]
|
||||||
- Create an issue in the AI repo with the milestone assigned:
|
|
||||||
|
|
||||||
```bash
|
## Suggested Encoding
|
||||||
tea issues create -r flowmade-one/ai --title "<title>" --description "<body>" --milestone "<milestone>"
|
- [ ] \`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
|
If vision updates are needed, present suggested changes and ask for approval.
|
||||||
tea milestones -f title,description
|
|
||||||
```
|
|
||||||
|
|
||||||
For each issue, automatically assign to the most relevant milestone by matching:
|
## When the Issue is Worked On
|
||||||
- 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
|
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
|
```markdown
|
||||||
## Context
|
# [Learning Title]
|
||||||
What task triggered this learning (brief).
|
|
||||||
|
|
||||||
## Problem / Observation
|
**Date**: YYYY-MM-DD
|
||||||
What was the friction point or insight.
|
**Context**: [Task that triggered this learning]
|
||||||
|
**Issue**: #XX
|
||||||
|
|
||||||
## Suggested Improvement
|
## Learning
|
||||||
Concrete, actionable change to make.
|
|
||||||
|
|
||||||
## Affected Files
|
[The specific insight]
|
||||||
- commands/xxx.md
|
|
||||||
- skills/xxx/SKILL.md
|
## 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
|
## Labels
|
||||||
|
|
||||||
Add appropriate labels:
|
Add appropriate labels to issues:
|
||||||
- `retrospective` - Always add this
|
- `learning` - Always add this
|
||||||
- `prompt-improvement` - For command/skill text changes
|
- `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
|
- `bug` - For things that are broken
|
||||||
|
|
||||||
## Guidelines
|
## Guidelines
|
||||||
|
|
||||||
- Be specific and actionable - vague issues won't get fixed
|
- **Always create issues on architecture repo** - regardless of which repo the retro runs in
|
||||||
- One issue per improvement (don't bundle unrelated things)
|
- **Be specific**: Vague insights can't be encoded
|
||||||
- Reference specific commands/skills when relevant
|
- **One issue per insight**: Don't bundle unrelated things
|
||||||
- Keep issues small and focused
|
- **Encoding happens later**: Retro captures the issue, encoding is separate work
|
||||||
- Skip creating issues for one-off edge cases that won't recur
|
- **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/vision-management/SKILL.md
|
||||||
@~/.claude/skills/gitea/SKILL.md
|
@~/.claude/skills/gitea/SKILL.md
|
||||||
|
|
||||||
|
This command manages **product-level** vision. For organization-level vision, use `/manifesto`.
|
||||||
|
|
||||||
## Architecture
|
## 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 |
|
Product vision inherits from and extends the organization manifesto.
|
||||||
|-------|---------|----------|
|
|
||||||
| **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.
|
|
||||||
|
|
||||||
## Process
|
## 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**:
|
2. **Check for product vision**: Look for `vision.md` in the current repo root
|
||||||
- Ask the user if they want to create one
|
|
||||||
|
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:
|
- Guide them through defining:
|
||||||
1. **Personas**: Who are we building for? (2-4 specific personas)
|
1. **Product personas**: Who does this product serve? (may extend org personas)
|
||||||
2. **Jobs to be done**: What are they trying to achieve?
|
2. **Product jobs**: What specific jobs does this product address?
|
||||||
3. **The problem**: What pain points exist today?
|
3. **The problem**: What pain points does this product solve?
|
||||||
4. **The solution**: How does this product address their jobs?
|
4. **The solution**: How does this product address those jobs?
|
||||||
5. **Guiding principles**: What beliefs guide decisions?
|
5. **Product principles**: Any product-specific principles (beyond org principles)?
|
||||||
6. **Non-goals**: What are we explicitly NOT doing?
|
6. **Product non-goals**: What is this product explicitly NOT doing?
|
||||||
- Create `vision.md` (do NOT include goals/progress - that's milestones)
|
- Create `vision.md`
|
||||||
- Ask about initial goals tied to personas/jobs, create as Gitea milestones
|
- Ask about initial goals, create as Gitea milestones
|
||||||
|
|
||||||
3. **If vision exists**:
|
4. **If vision exists**:
|
||||||
- Display the vision philosophy from `vision.md`
|
- Display organization context (if manifesto exists)
|
||||||
|
- Display the product vision from `vision.md`
|
||||||
- Show current milestones and their progress: `tea milestones`
|
- Show current milestones and their progress: `tea milestones`
|
||||||
- Check if `$1` specifies an action:
|
- Check if `$1` specifies an action:
|
||||||
- `goals`: Manage milestones (add, close, view progress)
|
- `goals`: Manage milestones (add, close, view progress)
|
||||||
- If no action specified, just display the current state
|
- If no action specified, just display the current state
|
||||||
|
|
||||||
4. **Managing Goals (milestones)**:
|
5. **Managing Goals (milestones)**:
|
||||||
```bash
|
```bash
|
||||||
# List milestones with progress
|
# List milestones with progress
|
||||||
tea milestones
|
tea milestones
|
||||||
|
|
||||||
# Create a new goal
|
# 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
|
# View issues in a milestone
|
||||||
tea milestones issues <milestone-name>
|
tea milestones issues <milestone-name>
|
||||||
@@ -60,37 +67,44 @@ Issues are assigned to milestones. Progress is visible through milestone complet
|
|||||||
## Output Format
|
## Output Format
|
||||||
|
|
||||||
```
|
```
|
||||||
## Who We Serve
|
## Organization Context
|
||||||
|
|
||||||
- **[Persona 1]**: [Brief description]
|
See manifesto for shared personas, beliefs, and principles.
|
||||||
- **[Persona 2]**: [Brief description]
|
[Link or note about manifesto.md location]
|
||||||
|
|
||||||
## What They're Trying to Achieve
|
## Product: [Name]
|
||||||
|
|
||||||
- "[Job to be done 1]"
|
### Who This Product Serves
|
||||||
- "[Job to be done 2]"
|
|
||||||
|
|
||||||
## 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]
|
[Summary of problem/solution from vision.md]
|
||||||
|
|
||||||
## Goals (Milestones)
|
### Goals (Milestones)
|
||||||
|
|
||||||
| Goal | For | Progress | Due |
|
| Goal | For | Progress | Due |
|
||||||
|------|-----|----------|-----|
|
|------|-----|----------|-----|
|
||||||
| [title] | [Persona] | 3/5 issues | [date] |
|
| [title] | [Persona] | 3/5 issues | [date] |
|
||||||
|
|
||||||
## Current Focus
|
### Current Focus
|
||||||
|
|
||||||
[Open milestones with nearest due dates or most activity]
|
[Open milestones with nearest due dates or most activity]
|
||||||
```
|
```
|
||||||
|
|
||||||
## Guidelines
|
## Guidelines
|
||||||
|
|
||||||
- vision.md is the stable "why" and "who" document - update rarely
|
- Product vision builds on organization manifesto - don't duplicate, extend
|
||||||
- Personas and jobs to be done are foundational - everything traces back to them
|
- Product personas can be more specific versions of org personas
|
||||||
- Milestones are actionable goals - each should serve a specific persona's job
|
- Product jobs should trace back to org-level jobs to be done
|
||||||
- Assign issues to milestones to track progress
|
- Milestones are product-specific goals toward the vision
|
||||||
- Use milestone descriptions for: persona, job, success criteria
|
- Use `/manifesto` for organization-level identity and beliefs
|
||||||
- Due dates on milestones are optional but help prioritization
|
- Use `/vision` for product-specific direction and goals
|
||||||
- If you can't tie work to a persona/job, question whether it should be done
|
- If this is the architecture repo itself, use `/manifesto` instead
|
||||||
|
|||||||
@@ -1,123 +1,175 @@
|
|||||||
---
|
---
|
||||||
name: vision-management
|
name: vision-management
|
||||||
description: Create, maintain, and evolve a product vision. Use when initializing a vision, updating goals, aligning work with vision, or connecting learnings to vision refinement.
|
description: Create, maintain, and evolve organization manifesto and product visions. Use when working with manifesto.md, vision.md, milestones, or aligning work with organizational direction.
|
||||||
---
|
---
|
||||||
|
|
||||||
# Vision Management
|
# Vision Management
|
||||||
|
|
||||||
How to create, maintain, and evolve a product vision for continuous improvement.
|
How to create, maintain, and evolve organizational direction at two levels: manifesto (organization) and vision (product).
|
||||||
|
|
||||||
## Architecture
|
## Architecture
|
||||||
|
|
||||||
The vision system has two layers:
|
| Level | Document | Purpose | Command | Location |
|
||||||
|
|-------|----------|---------|---------|----------|
|
||||||
|
| **Organization** | `manifesto.md` | Identity, shared personas, beliefs, principles | `/manifesto` | Architecture repo |
|
||||||
|
| **Product** | `vision.md` | Product-specific personas, jobs, solution | `/vision` | Product repos |
|
||||||
|
| **Goals** | Gitea milestones | Measurable progress toward vision | `/vision goals` | Per repo |
|
||||||
|
|
||||||
| Layer | Purpose | Location |
|
Product vision inherits from and extends the organization manifesto.
|
||||||
|-------|---------|----------|
|
|
||||||
| **vision.md** | North star philosophy (why, principles, non-goals) | File in repo root |
|
|
||||||
| **Milestones** | Goals with progress tracking | Gitea milestones |
|
|
||||||
|
|
||||||
- **vision.md** is stable - updated rarely when direction changes
|
---
|
||||||
- **Milestones** are actionable - created/closed as goals evolve
|
|
||||||
- **Issues** are assigned to milestones to track progress
|
|
||||||
|
|
||||||
## Vision Document Structure
|
## Manifesto (Organization Level)
|
||||||
|
|
||||||
The vision.md file should contain the stable "why" and "who" - not progress tracking:
|
The manifesto defines who we are as an organization. It lives in the architecture repo and applies across all products.
|
||||||
|
|
||||||
|
### Manifesto Structure
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Manifesto
|
||||||
|
|
||||||
|
## Who We Are
|
||||||
|
Organization identity - what makes us unique.
|
||||||
|
|
||||||
|
## Who We Serve
|
||||||
|
Shared personas across all products.
|
||||||
|
- **Persona Name**: Description, context, constraints
|
||||||
|
|
||||||
|
## What They're Trying to Achieve
|
||||||
|
Jobs to be done at the organization level.
|
||||||
|
- "Help me [outcome] without [pain]"
|
||||||
|
|
||||||
|
## What We Believe
|
||||||
|
Core beliefs that guide how we work.
|
||||||
|
### [Belief Category]
|
||||||
|
- Belief point
|
||||||
|
- Belief point
|
||||||
|
|
||||||
|
## Guiding Principles
|
||||||
|
Decision-making rules that apply everywhere.
|
||||||
|
1. **Principle**: Explanation
|
||||||
|
|
||||||
|
## Non-Goals
|
||||||
|
What the organization explicitly does NOT do.
|
||||||
|
- **Non-goal**: Why
|
||||||
|
```
|
||||||
|
|
||||||
|
### When to Update Manifesto
|
||||||
|
|
||||||
|
- **Rarely** - this is foundational identity
|
||||||
|
- When core beliefs change
|
||||||
|
- When adding/removing personas served
|
||||||
|
- When adding non-goals based on learnings
|
||||||
|
|
||||||
|
### Creating a Manifesto
|
||||||
|
|
||||||
|
1. Define organization identity (Who We Are)
|
||||||
|
2. Identify shared personas (2-4 max)
|
||||||
|
3. Articulate organization-level jobs to be done
|
||||||
|
4. Document core beliefs (especially about AI/development)
|
||||||
|
5. Establish guiding principles
|
||||||
|
6. Define non-goals
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Vision (Product Level)
|
||||||
|
|
||||||
|
The vision defines what a specific product does. It lives in each product repo and extends the manifesto.
|
||||||
|
|
||||||
|
### Vision Structure
|
||||||
|
|
||||||
```markdown
|
```markdown
|
||||||
# Vision
|
# Vision
|
||||||
|
|
||||||
## Who We Serve (Personas)
|
## Who This Product Serves
|
||||||
The people we're building for and what characterizes them.
|
Product-specific personas (may extend org personas).
|
||||||
|
- **Persona Name**: Product-specific context
|
||||||
|
|
||||||
- **Persona Name**: Brief description of who they are, their context, constraints
|
## What They're Trying to Achieve
|
||||||
|
Product-specific jobs to be done.
|
||||||
## What They're Trying to Achieve (Jobs to Be Done)
|
- "Help me [outcome] without [pain]"
|
||||||
The outcomes our personas are trying to accomplish - in their words.
|
|
||||||
|
|
||||||
- "Help me [achieve outcome] without [pain point]"
|
|
||||||
- "Help me [do thing] so I can [benefit]"
|
|
||||||
|
|
||||||
## The Problem
|
## The Problem
|
||||||
Current pain points that prevent our personas from achieving their jobs.
|
Pain points this product addresses.
|
||||||
|
|
||||||
## The Solution
|
## The Solution
|
||||||
How this product addresses the jobs to be done.
|
How this product solves those problems.
|
||||||
|
|
||||||
## Guiding Principles
|
## Product Principles
|
||||||
Core beliefs that guide decisions.
|
Product-specific principles (beyond org principles).
|
||||||
|
|
||||||
## Non-Goals
|
## Non-Goals
|
||||||
What we're explicitly NOT doing (and why).
|
What this product explicitly does NOT do.
|
||||||
```
|
```
|
||||||
|
|
||||||
Do NOT include goals, progress, or focus in vision.md - that's what milestones are for.
|
### When to Update Vision
|
||||||
|
|
||||||
## Defining Personas
|
- When product direction shifts
|
||||||
|
- When adding/changing personas served by this product
|
||||||
|
- When discovering new non-goals
|
||||||
|
- After major learnings from retros
|
||||||
|
|
||||||
Good personas are:
|
### Creating a Product Vision
|
||||||
- **Specific**: Not "developers" but "solo developers shipping MVPs"
|
|
||||||
- **Characterized**: Include constraints, context, priorities
|
|
||||||
- **Limited**: 2-4 personas max, or you're building for everyone (no one)
|
|
||||||
|
|
||||||
| Bad | Good |
|
1. Reference the organization manifesto
|
||||||
|-----|------|
|
2. Define product-specific personas (can extend org personas)
|
||||||
| "Users" | "Solo developer shipping side projects on evenings/weekends" |
|
3. Identify product-specific jobs to be done
|
||||||
| "Developers" | "Small team lead coordinating 2-5 engineers" |
|
4. Articulate the problem this product solves
|
||||||
| "Companies" | "Early-stage startup with no dedicated DevOps" |
|
5. Define the solution approach
|
||||||
|
6. Set product-specific principles (if any)
|
||||||
|
7. Document product non-goals
|
||||||
|
8. Create initial milestones
|
||||||
|
|
||||||
## Defining Jobs to Be Done
|
---
|
||||||
|
|
||||||
Jobs should be:
|
## Relationship: Manifesto → Vision
|
||||||
- **Outcome-focused**: What they want to achieve, not what they do
|
|
||||||
- **In their voice**: How they'd describe it, not technical jargon
|
|
||||||
- **Pain-aware**: Include what's hard about it today
|
|
||||||
|
|
||||||
Format: "Help me [outcome] without [pain]" or "Help me [action] so I can [benefit]"
|
```
|
||||||
|
Manifesto (org) Vision (product)
|
||||||
|
├── Shared Personas → Product Personas (more specific)
|
||||||
|
├── Org Jobs → Product Jobs (subset/extension)
|
||||||
|
├── Beliefs → (inherited, not duplicated)
|
||||||
|
├── Principles → Product Principles (additional)
|
||||||
|
└── Non-Goals → Product Non-Goals (additional)
|
||||||
|
```
|
||||||
|
|
||||||
| Bad | Good |
|
### Inheritance Model
|
||||||
|-----|------|
|
|
||||||
| "Git integration" | "Help me commit and push without remembering git commands" |
|
|
||||||
| "Issue tracking" | "Help me know what to work on next without checking 5 tools" |
|
|
||||||
| "Code review" | "Help me catch bugs before they ship without slowing down" |
|
|
||||||
|
|
||||||
## Creating a Vision
|
- **Personas**: Product personas can be more specific versions of org personas
|
||||||
|
- **Jobs**: Product jobs should trace back to org-level jobs
|
||||||
|
- **Beliefs**: Inherited from manifesto, not duplicated in vision
|
||||||
|
- **Principles**: Product can add specific principles; org principles apply automatically
|
||||||
|
- **Non-Goals**: Product adds its own; org non-goals apply automatically
|
||||||
|
|
||||||
When no vision exists:
|
### Example
|
||||||
|
|
||||||
1. **Define personas**: Who are we building for? (2-4 specific personas)
|
**Manifesto** (organization):
|
||||||
2. **Identify jobs to be done**: What are they trying to achieve?
|
```markdown
|
||||||
3. **Articulate the problem**: What pain points prevent them from achieving their jobs?
|
## Who We Serve
|
||||||
4. **Define the solution**: How does the product address these jobs?
|
- **Solo Developer**: Individual shipping side projects, time-constrained
|
||||||
5. **Set guiding principles**: What beliefs guide decisions?
|
```
|
||||||
6. **Document non-goals**: What are you explicitly NOT doing?
|
|
||||||
7. **Create initial milestones**: 3-5 measurable goals tied to personas/jobs
|
|
||||||
|
|
||||||
### Good Goals (Milestones)
|
**Vision** (product - e.g., CLI tool):
|
||||||
|
```markdown
|
||||||
|
## Who This Product Serves
|
||||||
|
- **Solo Developer (CLI user)**: Uses terminal daily, prefers keyboard over GUI
|
||||||
|
```
|
||||||
|
|
||||||
|
The product persona extends the org persona with product-specific context.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Milestones (Goals)
|
||||||
|
|
||||||
|
Milestones are product-level goals that track progress toward the vision.
|
||||||
|
|
||||||
|
### Good Milestones
|
||||||
|
|
||||||
- Specific and measurable
|
- Specific and measurable
|
||||||
- Tied to a persona and job to be done
|
- Tied to a persona and job to be done
|
||||||
- Outcome-focused (not activity-focused)
|
- Outcome-focused (not activity-focused)
|
||||||
- Have clear success criteria in the description
|
- Include success criteria in description
|
||||||
|
|
||||||
| Bad | Good |
|
|
||||||
|-----|------|
|
|
||||||
| "Improve performance" | "Page load under 2 seconds" |
|
|
||||||
| "Better UX" | "User can complete checkout in under 60 seconds" |
|
|
||||||
| "More features" | "Support 3 export formats (CSV, JSON, PDF)" |
|
|
||||||
|
|
||||||
### Tying Milestones to Personas
|
|
||||||
|
|
||||||
Each milestone should clearly serve a persona's job to be done:
|
|
||||||
|
|
||||||
```
|
|
||||||
Milestone: "Automate routine git workflows"
|
|
||||||
For: Solo developer
|
|
||||||
Job: "Help me commit and push without remembering git commands"
|
|
||||||
Success: /commit, /pr commands handle 80% of git workflows
|
|
||||||
```
|
|
||||||
|
|
||||||
Include persona context in milestone descriptions:
|
|
||||||
```bash
|
```bash
|
||||||
tea milestones create --title "Automate routine git workflows" \
|
tea milestones create --title "Automate routine git workflows" \
|
||||||
--description "For: Solo developer
|
--description "For: Solo developer
|
||||||
@@ -125,35 +177,14 @@ Job: Ship without context switching to git commands
|
|||||||
Success: /commit and /pr commands handle 80% of workflows"
|
Success: /commit and /pr commands handle 80% of workflows"
|
||||||
```
|
```
|
||||||
|
|
||||||
## Managing Goals with Milestones
|
### Milestone-to-Vision Alignment
|
||||||
|
|
||||||
```bash
|
Every milestone should trace to:
|
||||||
# List milestones with progress
|
- A persona (from vision or manifesto)
|
||||||
tea milestones
|
- A job to be done (from vision)
|
||||||
tea milestones -f title,items_open,items_closed,state
|
- A measurable outcome
|
||||||
|
|
||||||
# Create a new goal
|
---
|
||||||
tea milestones create --title "Automate repetitive workflows" \
|
|
||||||
--description "Success: 80% of routine tasks handled by slash commands"
|
|
||||||
|
|
||||||
# View issues in a milestone
|
|
||||||
tea milestones issues "Automate repetitive workflows"
|
|
||||||
|
|
||||||
# Close a completed goal
|
|
||||||
tea milestones close "Automate repetitive workflows"
|
|
||||||
```
|
|
||||||
|
|
||||||
### Assigning Issues to Milestones
|
|
||||||
|
|
||||||
When creating issues, assign them to the relevant milestone:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
tea issues create --title "Add /commit command" \
|
|
||||||
--description "..." \
|
|
||||||
--milestone "Automate repetitive workflows"
|
|
||||||
```
|
|
||||||
|
|
||||||
Progress is automatically tracked through open/closed issue counts.
|
|
||||||
|
|
||||||
## Aligning Issues with Vision
|
## Aligning Issues with Vision
|
||||||
|
|
||||||
@@ -161,50 +192,49 @@ When creating or reviewing issues:
|
|||||||
|
|
||||||
1. **Check persona alignment**: Which persona does this serve?
|
1. **Check persona alignment**: Which persona does this serve?
|
||||||
2. **Check job alignment**: Which job to be done does this enable?
|
2. **Check job alignment**: Which job to be done does this enable?
|
||||||
3. **Check goal alignment**: Does this issue support a milestone?
|
3. **Check milestone alignment**: Does this issue support a goal?
|
||||||
4. **Assign to milestone**: Link the issue to the relevant goal
|
4. **Assign to milestone**: Link the issue to the relevant goal
|
||||||
5. **Prioritize by focus**: Issues in priority milestones get worked first
|
|
||||||
6. **Flag misalignment**: Issues without clear persona/milestone need justification
|
|
||||||
|
|
||||||
Every issue should trace back to: "This helps [persona] achieve [job] by [outcome]."
|
Every issue should trace back to: "This helps [persona] achieve [job] by [outcome]."
|
||||||
|
|
||||||
### Identifying Gaps
|
### Identifying Gaps
|
||||||
|
|
||||||
Compare vision to current work:
|
|
||||||
|
|
||||||
- **Underserved personas**: Which personas have few milestones/issues?
|
- **Underserved personas**: Which personas have few milestones/issues?
|
||||||
- **Unaddressed jobs**: Which jobs to be done have no work toward them?
|
- **Unaddressed jobs**: Which jobs to be done have no work toward them?
|
||||||
- **Empty milestones**: Which milestones have no issues?
|
- **Empty milestones**: Which milestones have no issues?
|
||||||
- **Stalled milestones**: Which milestones have no recent progress?
|
- **Orphan issues**: Issues without a milestone need justification
|
||||||
- **Orphan issues**: Are there issues without a milestone?
|
|
||||||
|
|
||||||
## Connecting Retros to Vision
|
---
|
||||||
|
|
||||||
After a retrospective:
|
|
||||||
|
|
||||||
1. **Review learnings**: Any that affect the vision or goals?
|
|
||||||
2. **Milestone changes**: Should any goals be added, closed, or modified?
|
|
||||||
3. **Non-goal additions**: Did we learn something to add to vision.md?
|
|
||||||
4. **Progress check**: Did completed work close any milestones?
|
|
||||||
|
|
||||||
### Retro-to-Vision Questions
|
|
||||||
|
|
||||||
- "Did this work reveal a new goal we should add as a milestone?"
|
|
||||||
- "Did we learn something that should become a non-goal in vision.md?"
|
|
||||||
- "Should we close or modify any milestones based on what we learned?"
|
|
||||||
- "Are any milestones ready to close?"
|
|
||||||
|
|
||||||
## Continuous Improvement Loop
|
## Continuous Improvement Loop
|
||||||
|
|
||||||
```
|
```
|
||||||
Vision → Milestones → Issues → Work → Retro → (Vision/Milestones updated)
|
Manifesto → Vision → Milestones → Issues → Work → Retro → (updates)
|
||||||
|
↓
|
||||||
|
Architecture repo issues
|
||||||
|
↓
|
||||||
|
Encoded into learnings +
|
||||||
|
skills/commands/agents
|
||||||
```
|
```
|
||||||
|
|
||||||
1. **Vision** defines why and principles (stable)
|
1. **Manifesto** defines organizational identity (very stable)
|
||||||
2. **Milestones** define measurable goals
|
2. **Vision** defines product direction (stable)
|
||||||
3. **Issues** are work items toward those goals
|
3. **Milestones** define measurable goals (evolve)
|
||||||
4. **Work** implements the issues
|
4. **Issues** are work items toward goals
|
||||||
5. **Retros** capture learnings
|
5. **Work** implements the issues
|
||||||
6. **Updates** refine vision and create/close milestones
|
6. **Retros** create issues on architecture repo
|
||||||
|
7. **Encoding** turns insights into learnings and system improvements
|
||||||
|
|
||||||
The vision is stable. The milestones evolve as you learn and achieve goals.
|
---
|
||||||
|
|
||||||
|
## Quick Reference
|
||||||
|
|
||||||
|
| Question | Answer |
|
||||||
|
|----------|--------|
|
||||||
|
| Where do shared personas live? | `manifesto.md` in architecture repo |
|
||||||
|
| Where do product personas live? | `vision.md` in product repo |
|
||||||
|
| Where do beliefs live? | `manifesto.md` only (inherited) |
|
||||||
|
| Where do goals live? | Gitea milestones (per repo) |
|
||||||
|
| What command for org vision? | `/manifesto` |
|
||||||
|
| What command for product vision? | `/vision` |
|
||||||
|
| What repo for learnings? | Architecture repo |
|
||||||
|
|||||||
Reference in New Issue
Block a user