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

name, description, version

name	description	version
Vision Discovery	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.	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.