architecture/skills/vision-management/SKILL.md

name, description

name	description
vision-management	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:

# 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:

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

# 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:

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.