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

# 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

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