Hugo Nijhuis
28242d44cc
Refactored the vision system to separate concerns: - vision.md remains the stable "north star" philosophy document - Gitea milestones now track goals with automatic progress via issue counts - Updated /vision, /retro, and /create-issue commands to auto-assign milestones 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
144 lines
4.2 KiB
Markdown
144 lines
4.2 KiB
Markdown
---
|
|
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.
|
|
---
|
|
|
|
# Vision Management
|
|
|
|
How to create, maintain, and evolve a product vision for continuous improvement.
|
|
|
|
## Architecture
|
|
|
|
The vision system has two layers:
|
|
|
|
| Layer | Purpose | Location |
|
|
|-------|---------|----------|
|
|
| **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
|
|
|
|
The vision.md file should contain the stable "why" - not progress tracking:
|
|
|
|
```markdown
|
|
# Vision
|
|
|
|
## The Problem
|
|
What problem does this product solve? Who benefits?
|
|
|
|
## The Solution
|
|
How does this product solve the problem?
|
|
|
|
## Guiding Principles
|
|
Core beliefs that guide decisions.
|
|
|
|
## Non-Goals
|
|
What we're explicitly NOT doing.
|
|
```
|
|
|
|
Do NOT include goals, progress, or focus in vision.md - that's what milestones are for.
|
|
|
|
## Creating a Vision
|
|
|
|
When no vision exists:
|
|
|
|
1. **Identify the problem**: What pain point does this solve?
|
|
2. **Define the solution**: How does the product address it?
|
|
3. **Set guiding principles**: What beliefs guide decisions?
|
|
4. **Document non-goals**: What are you explicitly NOT doing?
|
|
5. **Create initial milestones**: 3-5 measurable goals
|
|
|
|
### Good Goals (Milestones)
|
|
|
|
- Specific and measurable
|
|
- Outcome-focused (not activity-focused)
|
|
- Have clear success criteria in the 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)" |
|
|
|
|
## Managing Goals with Milestones
|
|
|
|
```bash
|
|
# List milestones with progress
|
|
tea milestones
|
|
tea milestones -f title,items_open,items_closed,state
|
|
|
|
# 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
|
|
|
|
When creating or reviewing issues:
|
|
|
|
1. **Check goal alignment**: Does this issue support a milestone?
|
|
2. **Assign to milestone**: Link the issue to the relevant goal
|
|
3. **Prioritize by focus**: Issues in priority milestones get worked first
|
|
4. **Flag misalignment**: Issues without a milestone need justification
|
|
|
|
### Identifying Gaps
|
|
|
|
Compare milestones to current backlog:
|
|
|
|
- Which milestones have no issues?
|
|
- Which milestones have stalled (no recent progress)?
|
|
- 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
|
|
|
|
```
|
|
Vision → Milestones → Issues → Work → Retro → (Vision/Milestones updated)
|
|
```
|
|
|
|
1. **Vision** defines why and principles (stable)
|
|
2. **Milestones** define measurable goals
|
|
3. **Issues** are work items toward those goals
|
|
4. **Work** implements the issues
|
|
5. **Retros** capture learnings
|
|
6. **Updates** refine vision and create/close milestones
|
|
|
|
The vision is stable. The milestones evolve as you learn and achieve goals.
|