architecture/skills/vision-management/SKILL.md

---
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" and "who" - not progress tracking:

```markdown
# Vision

## Who We Serve (Personas)
The people we're building for and what characterizes them.

- **Persona Name**: Brief description of who they are, their context, constraints

## What They're Trying to Achieve (Jobs to Be Done)
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
Current pain points that prevent our personas from achieving their jobs.

## The Solution
How this product addresses the jobs to be done.

## Guiding Principles
Core beliefs that guide decisions.

## Non-Goals
What we're explicitly NOT doing (and why).
```

Do NOT include goals, progress, or focus in vision.md - that's what milestones are for.

## Defining Personas

Good personas are:
- **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 |
|-----|------|
| "Users" | "Solo developer shipping side projects on evenings/weekends" |
| "Developers" | "Small team lead coordinating 2-5 engineers" |
| "Companies" | "Early-stage startup with no dedicated DevOps" |

## Defining Jobs to Be Done

Jobs should be:
- **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]"

| Bad | Good |
|-----|------|
| "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

When no vision exists:

1. **Define personas**: Who are we building for? (2-4 specific personas)
2. **Identify jobs to be done**: What are they trying to achieve?
3. **Articulate the problem**: What pain points prevent them from achieving their jobs?
4. **Define the solution**: How does the product address these jobs?
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)

- Specific and measurable
- Tied to a persona and job to be done
- 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)" |

### 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
tea milestones create --title "Automate routine git workflows" \
  --description "For: Solo developer
Job: Ship without context switching to git commands
Success: /commit and /pr commands handle 80% of workflows"
```

## 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 persona alignment**: Which persona does this serve?
2. **Check job alignment**: Which job to be done does this enable?
3. **Check goal alignment**: Does this issue support a milestone?
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]."

### Identifying Gaps

Compare vision to current work:

- **Underserved personas**: Which personas have few milestones/issues?
- **Unaddressed jobs**: Which jobs to be done have no work toward them?
- **Empty milestones**: Which milestones have no issues?
- **Stalled milestones**: Which milestones have no recent progress?
- **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

```
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.