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.

Vision Document Location

The vision lives in two places:

1. vision.md at repo root - Source of truth, versionable
2. Gitea issue labeled vision - Integrates with issue workflow

Keep these in sync. The file is authoritative; the issue mirrors it.

Vision Document Structure

# Product Vision

## Purpose
Why this product exists. The problem it solves.

## Goals
1. [Goal 1] - [Success metric]
2. [Goal 2] - [Success metric]
3. [Goal 3] - [Success metric]

## Current Focus
What we're prioritizing now and why.

## Non-Goals
What we're explicitly NOT doing.

## Progress
- [Goal 1]: [Status/progress]
- [Goal 2]: [Status/progress]

## Last Updated
[Date] - [What changed]

Creating a Vision

When no vision exists:

1. Identify the purpose: What problem does this product solve? Who benefits?
2. Define 3-5 goals: Concrete, measurable outcomes
3. Set success metrics: How will you know each goal is achieved?
4. Choose current focus: Which 1-2 goals are priorities right now?
5. Document non-goals: What are you explicitly NOT doing?

Good Goals

• Specific and measurable
• Outcome-focused (not activity-focused)
• Have clear success criteria

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)"

Updating the Vision

Update the vision when:

• A goal is achieved (update progress, possibly add new goal)
• Learnings from retros reveal new priorities
• Strategic direction changes
• A non-goal becomes a goal (or vice versa)

Update Process

1. Read current vision
2. Identify what needs to change
3. Draft the update
4. Present changes for approval
5. Update vision.md
6. Sync to Gitea issue

Aligning Issues with Vision

When creating or reviewing issues:

1. Check goal alignment: Does this issue support a vision goal?
2. Tag appropriately: Reference the goal in the issue description
3. Prioritize by vision: Issues supporting current focus get priority
4. Flag misalignment: Issues that don't align with any goal need justification

Alignment Check Template

## Vision Alignment
Supports: Goal 2 (Security)
Priority: High (current focus area)

Identifying Gaps

Compare vision goals to current backlog:

• Which goals have no supporting issues?
• Which goals have stalled (no recent progress)?
• Are there issues that don't align with any goal?

Connecting Retros to Vision

After a retrospective:

1. Review learnings: Any that affect the vision?
2. Goal changes: Should any goals be added, removed, or modified?
3. Non-goal additions: Did we learn something we should explicitly avoid?
4. Progress updates: Did completed work advance any goals?

Retro-to-Vision Questions

• "Did this work reveal a new priority we should add as a goal?"
• "Did we learn something that should become a non-goal?"
• "Should our current focus shift based on what we learned?"
• "Did this work make progress on any goals?"

Vision Issue in Gitea

Create/update a Gitea issue that mirrors the vision:

# Create vision issue
tea issues create --title "Product Vision" --description "$(cat vision.md)" --labels "vision"

# Update existing vision issue
tea issues edit <issue-number> --description "$(cat vision.md)"

Benefits of the vision issue:

• Other issues can reference it (Supports #N)
• Visible in backlog alongside work items
• Provides discussion space for vision questions

Continuous Improvement Loop

Vision → Issues → Work → Retro → Vision (updated)

1. Vision defines what success looks like
2. Issues are created to achieve vision goals
3. Work implements the issues
4. Retros capture learnings from the work
5. Vision updates incorporate learnings (loop continues)

The vision is a living document that evolves as you learn.