zhongwei/gh-sjnims-requirements-expert-plugins-requirements-expert
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:57:33 +08:00
commit b4a8193ca4
28 changed files with 7229 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

202
skills/vision-discovery/SKILL.md Normal file
View File

@@ -0,0 +1,202 @@
---
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.

178
skills/vision-discovery/references/vision-template.md Normal file
View File

@@ -0,0 +1,178 @@
# Vision Document Template
Use this template when creating a vision issue in GitHub Projects. Copy the structure below into the issue description, then fill in each section based on the discovery process.
---
## Product Vision: [Product Name]
### Problem Statement
**What problem exists?**
[Describe the core problem being addressed. Be specific about the pain points, challenges, or inefficiencies that currently exist.]
**Why does this problem matter?**
[Explain the impact of this problem—costs, frustration, missed opportunities, risks, etc. Quantify when possible.]
**Current State:**
[How do people currently address this problem? What workarounds, competitors, or manual processes exist? Why are these insufficient?]
---
### Target Users
**Primary Users:**
- **Who:** [Role, title, context]
- **Characteristics:** [Expertise level, environment, constraints]
- **Goals:** [What they're trying to achieve]
- **Pain Points:** [Specific frustrations or challenges they face]
**Secondary Users (if applicable):**
- **Who:** [Other stakeholders, admins, support staff]
- **Relationship:** [How they interact with primary users or the product]
**User Personas:**
[Optional: Create 1-2 concrete personas with names, backgrounds, and specific scenarios]
---
### Solution Overview
**In one sentence:**
[Elevator pitch: What this product does and who it's for]
**Core Capabilities:**
1. [First major capability]
2. [Second major capability]
3. [Third major capability]
[Describe the 2-3 essential things this product must do to deliver value]
**Unique Value Proposition:**
[What makes this solution different from or better than alternatives? Why would users choose this?]
---
### Core Value Proposition
**For Users:**
[How does this solution make users' lives better? What specific benefits do they gain?]
**Key Benefits:**
- [Benefit 1: e.g., Save 10 hours/week on manual reporting]
- [Benefit 2: e.g., Increase decision confidence with real-time data]
- [Benefit 3: e.g., Reduce errors from manual data entry]
**Differentiation:**
[Why is this better than current alternatives? What's the compelling reason to switch/adopt?]
---
### Success Metrics
**How we'll measure success:**
| Metric | Target | Timeframe |
|--------|--------|-----------|
| [Metric 1: e.g., Active Users] | [e.g., 10,000] | [e.g., 12 months] |
| [Metric 2: e.g., Weekly Retention] | [e.g., 70%] | [e.g., 6 months] |
| [Metric 3: e.g., Time Saved per User] | [e.g., 10 hrs/week] | [e.g., 3 months] |
**User Success Indicators:**
[What user behaviors or outcomes indicate the product is delivering value?]
- [Indicator 1]
- [Indicator 2]
- [Indicator 3]
---
### Scope & Boundaries
**In Scope:**
[What IS included in this vision]
- [Capability 1]
- [Capability 2]
- [Capability 3]
**Out of Scope:**
[What is explicitly NOT included—define boundaries to prevent scope creep]
- [Not doing 1]
- [Not doing 2]
- [Not doing 3]
**Future Considerations:**
[Things that might be considered later but aren't part of the initial vision]
- [Future item 1]
- [Future item 2]
---
### Strategic Alignment
**Business Goals:**
[How does this vision align with broader organizational or business objectives?]
**Market Opportunity:**
[What market need or opportunity does this address? Size, growth, trends?]
**Competitive Landscape:**
[Who else is in this space? How do we compare or differentiate?]
---
### Risks & Assumptions
**Key Assumptions:**
[What are we assuming to be true that could impact success?]
1. [Assumption 1]
2. [Assumption 2]
3. [Assumption 3]
**Known Risks:**
[What could go wrong or prevent success?]
- [Risk 1 + mitigation strategy]
- [Risk 2 + mitigation strategy]
---
## Notes
[Any additional context, background, or considerations]
---
## Next Steps
After finalizing this vision:
1. Share with stakeholders for feedback and alignment
2. Identify epics that will deliver on this vision
3. Reference this vision when prioritizing and making product decisions
4. Review and update quarterly or when significant learnings emerge