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

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

```markdown
# 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

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

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