gh-sjnims-requirements-expert-plugins-requirements-expert/skills/vision-discovery/SKILL.md

---
name: Vision Discovery
description: This skill should be used when the user asks to "discover vision", "create a vision", "define product vision", "document vision", "what should my vision be", "help me with vision", or when starting a new requirements project and needs to establish the foundational product vision before identifying epics or stories.
version: 0.2.0
---

# Vision Discovery

## Overview

Vision discovery is the critical first step in the requirements lifecycle. A clear, well-articulated product vision provides direction for all subsequent work—epics, user stories, and tasks all flow from and align with the vision. This skill guides the process of discovering and documenting a compelling product vision through structured questioning and best practices.

## Purpose

A product vision defines:
- **What problem** is being solved
- **Who** will benefit from the solution
- **Why** this solution matters
- **What success looks like** when achieved

The vision serves as a north star for all product decisions, helping teams stay aligned and prioritize work that delivers the most value.

## When to Use This Skill

Use vision discovery when:
- Starting a new product or feature from scratch
- The user has a vague idea but needs help articulating it clearly
- Existing vision is unclear, outdated, or poorly defined
- Team lacks alignment on product direction
- Before identifying epics (vision must exist first)

## Vision Discovery Process

### Step 1: Understand the Problem Space

Begin by exploring the problem being solved. Ask probing questions to uncover the root issue:

**Essential Questions:**
- What problem are you trying to solve?
- Who experiences this problem?
- How do they currently address it (workarounds, competitors, manual processes)?
- Why is the current situation unsatisfactory?
- What happens if this problem remains unsolved?

**Technique:** Use the "5 Whys" technique to dig deeper into root causes. When the user describes a problem, ask "why is that a problem?" repeatedly to uncover underlying issues.

### Step 2: Identify Target Users

Clearly define who will use and benefit from the solution:

**Essential Questions:**
- Who is the primary user/customer?
- Are there secondary users (admins, support staff, etc.)?
- What are their key characteristics (role, expertise level, context)?
- What are their goals and motivations?
- What pain points do they experience?

**Output:** Create user personas or archetypes with specific, concrete details. Avoid vague descriptions like "business users"—be specific: "marketing managers at mid-size B2B companies tracking campaign ROI."

### Step 3: Define the Solution Vision

Articulate what the solution is and how it addresses the problem:

**Essential Questions:**
- In one sentence, what does this product do?
- What makes this solution different or better than alternatives?
- What are the 2-3 core capabilities that define this product?
- What is explicitly NOT part of this vision (scope boundaries)?

**Technique:** Use the "elevator pitch" format: "For [target users] who [need/problem], [product name] is a [category] that [key benefit]. Unlike [alternatives], our product [unique differentiator]."

### Step 4: Establish Success Metrics

Define how success will be measured:

**Essential Questions:**
- How will we know if this product is successful?
- What metrics matter most (usage, revenue, satisfaction, efficiency)?
- What does "good" look like in 6 months? 1 year?
- What user behaviors indicate value delivery?

**Output:** Specific, measurable success criteria. Avoid vanity metrics—focus on indicators of genuine value and impact.

### Step 5: Document the Vision

Create a structured vision document in GitHub Projects as an issue with Type: Vision. Use the template structure from `${CLAUDE_PLUGIN_ROOT}/skills/vision-discovery/references/vision-template.md`.

**Core Sections:**
1. **Problem Statement** - What problem exists and why it matters
2. **Target Users** - Who will use this and their key characteristics
3. **Solution Overview** - What the product is and does
4. **Core Value Proposition** - Why users will choose this solution
5. **Success Metrics** - How success will be measured
6. **Scope & Boundaries** - What's included and explicitly excluded

## Best Practices

### Keep It Concise

A vision should be digestible in 5-10 minutes. Aim for:
- 1-2 paragraphs for each major section
- Total length: 500-1,000 words
- Clear, jargon-free language

### Make It Inspiring Yet Realistic

Balance ambition with achievability:
- Articulate a compelling future state
- Ground it in real user needs and market realities
- Avoid buzzwords and hype
- Focus on genuine value creation

### Focus on "Why" Not "How"

The vision defines direction, not implementation:
- Describe outcomes and benefits, not technical solutions
- Avoid specifying features or architecture
- Leave room for discovery during epic and story creation
- Answer "what problem" and "why it matters," not "how we'll build it"

### Ensure Alignment

Before finalizing the vision:
- Review with key stakeholders
- Confirm it resonates with target users
- Verify it aligns with business goals
- Check that success metrics are measurable

### Iterate and Refine

Vision is not set in stone:
- Expect to refine as you learn more
- Update when market conditions or user needs change
- Use feedback from epic and story creation to improve clarity
- Treat vision as a living document

## Integration with GitHub Projects

Create the vision as a GitHub issue in the relevant GitHub Project:

**Issue Title:** "Product Vision: [Product Name]"

**Issue Description:** Full vision document with all sections

**Custom Fields:**
- Type: Vision
- Status: Active
- Priority: (Not applicable for vision)

**Labels:**
- `type:vision`

All epics will be created as child issues of this vision issue, establishing clear traceability.

## Common Pitfalls to Avoid

### Too Vague

❌ "Build a platform for users to interact"
✅ "Enable marketing managers to track campaign ROI across channels in real-time"

### Too Prescriptive

❌ "Build a React app with a dashboard showing charts"
✅ "Provide visibility into campaign performance to enable data-driven decisions"

### Scope Creep

❌ Vision that includes everything: e-commerce, social, analytics, AI, blockchain...
✅ Focused vision with clear boundaries: "Campaign ROI tracking, NOT creative design or email delivery"

### Unmeasurable Success

❌ "Be the best product in the market"
✅ "Achieve 10,000 active users with 70%+ weekly retention within 12 months"

## Quick Reference: Vision Discovery Flow

1. **Problem Space** → Understand what problem exists and why it matters
2. **Target Users** → Define who experiences the problem and will use the solution
3. **Solution Vision** → Articulate what the solution is and its core value
4. **Success Metrics** → Establish measurable success criteria
5. **Document** → Create vision issue in GitHub Projects
6. **Validate** → Review with stakeholders and refine
7. **Proceed** → Move to epic identification once vision is solid

## Additional Resources

### Reference Files

For detailed vision templates and examples:
- **`${CLAUDE_PLUGIN_ROOT}/skills/vision-discovery/references/vision-template.md`** - Complete vision template with all sections and guidance

## Next Steps

After completing vision discovery:
1. Create the vision issue in GitHub Projects
2. Share with stakeholders for feedback
3. Proceed to epic identification using the epic-identification skill
4. Reference the vision throughout all subsequent requirements work

The vision is the foundation—invest time to get it right before moving to epics and stories.