My-opencode-config user-story-fundamentals
User Story Fundamentals - Capturing User-Centered Requirements
install
source · Clone the upstream repo
git clone https://github.com/flpbalada/my-opencode-config
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/flpbalada/my-opencode-config "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/user-story-fundamentals" ~/.claude/skills/flpbalada-my-opencode-config-user-story-fundamentals && rm -rf "$T"
manifest:
skills/user-story-fundamentals/SKILL.mdsource content
User Story Fundamentals - Capturing User-Centered Requirements
A structured framework for capturing product requirements from the user's perspective. User stories help teams understand who needs a feature, what they want to accomplish, and why it matters.
When to Use This Skill
- Writing backlog items
- Defining feature requirements
- Prioritizing development work
- Communicating with development teams
- Breaking down epics into actionable work
- Ensuring user focus in product decisions
User Story Format
THE STANDARD TEMPLATE "As a [type of user], I want [some goal], so that [some reason/benefit]." Components: ┌─────────────────────────────────────────────────────┐ │ WHO: The user persona or role │ │ WHAT: The desired functionality or goal │ │ WHY: The business value or user benefit │ └─────────────────────────────────────────────────────┘ This format shifts focus from WRITING about requirements to TALKING about them, with users at the center.
Core Components
WHO - User Persona
Specificity Spectrum: Generic (avoid): ├── "As a user..." └── "As a customer..." Better: ├── "As a first-time visitor..." ├── "As a returning customer..." ├── "As an admin user..." └── "As a mobile user..." Best (with job context): ├── "As a marketing manager who needs weekly reports..." ├── "As a parent shopping for school supplies..." ├── "As a developer debugging production issues..." └── "As a sales rep preparing for a client meeting..."
WHAT - Desired Functionality
Focus on GOALS, not IMPLEMENTATION: ❌ "I want a blue button in the header" (prescriptive, limits solutions) ✓ "I want to quickly access my saved items" (goal-focused, enables creativity) ❌ "I want a REST API endpoint" (technical implementation) ✓ "I want to integrate my data with external tools" (user goal, flexible implementation)
WHY - Business Value
The "So That" Connection: This part explains: ├── What pain it solves ├── What value it creates ├── Why this matters to the user └── How it connects to business goals Without "so that": "As a user, I want to filter search results" → Why? What's the actual need? With "so that": "As a user, I want to filter search results so that I can find relevant items faster when browsing large catalogs" → Clear value, enables better solutions
INVEST Criteria
QUALITY CHECKLIST FOR USER STORIES I - Independent │ Can be developed and delivered separately │ No tight coupling to other stories │ N - Negotiable │ Details open to discussion │ Not a rigid contract │ V - Valuable │ Delivers real value to user or business │ Not just technical tasks │ E - Estimable │ Team can estimate effort │ Clear enough to size │ S - Small │ Fits within single sprint │ If too big, split it │ T - Testable │ Has clear acceptance criteria │ Can verify when complete
Acceptance Criteria
Definition
ACCEPTANCE CRITERIA (AC) Purpose: Define what makes the story "done" Format: Specific, testable conditions Example Story: "As a user, I want to reset my password via email so that I can regain access if I forget it" Acceptance Criteria: □ User can request reset from login page □ Email sent within 60 seconds of request □ Reset link expires after 24 hours □ Link works only once □ Password must meet security requirements □ User receives confirmation after successful reset
Writing Good AC
| Characteristic | Example |
|---|---|
| Specific | "Within 60 seconds" not "quickly" |
| Testable | "Email contains reset link" - can verify |
| Outcome-focused | "User can access account" not "system sends" |
| Complete | Covers happy path AND edge cases |
Prioritization Framework
RICE Scoring
RICE = (Reach × Impact × Confidence) / Effort Reach: How many users affected per time period? (100 users/month, 1000 users/quarter) Impact: How much will it move the needle? 3 = Massive, 2 = High, 1 = Medium, 0.5 = Low, 0.25 = Minimal Confidence: How sure are we about estimates? 100% = High, 80% = Medium, 50% = Low Effort: Person-months of work (0.5, 1, 2, 3...) Higher RICE score = Higher priority
MoSCoW Method
CATEGORIZATION FOR RELEASE PLANNING MUST Have (Non-negotiable) ├── Critical for release ├── Legal/compliance requirements └── Core value proposition SHOULD Have (Important) ├── High value but not critical ├── Workarounds exist └── Strong user demand COULD Have (Nice to have) ├── Desired but not necessary ├── Easy wins if time permits └── Lower user impact WON'T Have (Not this time) ├── Explicitly out of scope ├── Future consideration └── Documented for later
Story Splitting Techniques
When to Split
SPLIT IF: ├── Can't complete in one sprint ├── Story points > 13 (or team max) ├── Multiple distinct user values ├── Contains "and" connecting features └── Too many acceptance criteria
Splitting Methods
1. BY WORKFLOW STEPS Original: "User can complete purchase" Split: ├── User can add items to cart ├── User can enter shipping info ├── User can enter payment info └── User can confirm and place order 2. BY USER TYPE Original: "User can view dashboard" Split: ├── Admin can view full dashboard ├── Manager can view team metrics └── User can view personal stats 3. BY OPERATIONS (CRUD) Original: "User can manage contacts" Split: ├── User can create contact ├── User can view contact details ├── User can edit contact └── User can delete contact 4. BY DATA VARIATIONS Original: "User can import data" Split: ├── User can import CSV files ├── User can import Excel files └── User can import from API 5. BY ACCEPTANCE CRITERIA Original: "User can search products" Split: ├── User can basic keyword search ├── User can filter by category ├── User can sort results └── User can save search
Definition of Done vs. Acceptance Criteria
DEFINITION OF DONE (DoD) ACCEPTANCE CRITERIA (AC) ──────────────────────── ──────────────────────── Universal checklist Story-specific conditions Same for all stories Unique per story Quality standard Functional requirements DoD Examples: AC Examples: □ Code reviewed □ User can X □ Tests written □ System does Y □ Documentation updated □ Data validates as Z □ No critical bugs □ Performance meets N
Story Template
## User Story **ID:** [PROJ-123] **Title:** [Brief descriptive title] ### Story As a [specific user type], I want [goal/desire], so that [benefit/value]. ### Acceptance Criteria - [ ] [Specific, testable condition 1] - [ ] [Specific, testable condition 2] - [ ] [Specific, testable condition 3] ### Notes - [Additional context] - [Technical considerations] - [Dependencies] ### Attachments - [Link to designs] - [Link to research] ### Estimation - **Story Points:** [X] - **Priority:** [High/Medium/Low] - **Sprint:** [Sprint N]
Real-World Examples
E-commerce
Story: Password-less Login As a returning customer, I want to login using a magic link sent to my email, so that I can access my account without remembering passwords. Acceptance Criteria: □ User enters email on login page □ "Send magic link" option available □ Email received within 30 seconds □ Link valid for 15 minutes □ One-click login from email □ User lands on their dashboard after login □ Link cannot be reused after login
SaaS Product
Story: Team Invitation As an account admin, I want to invite team members via email, so that I can onboard my team without manual account creation. Acceptance Criteria: □ Admin can enter multiple email addresses □ Invitation email clearly explains next steps □ Invited user can set their own password □ Admin can see pending invitations □ Admin can revoke pending invitations □ Duplicate email addresses are prevented □ Admin can set role during invitation
Common Mistakes
ANTI-PATTERNS TO AVOID ❌ Implementation as story "Create database table for users" → Not user value, technical task ❌ Missing "so that" "As a user, I want to search" → Why? What problem does this solve? ❌ Too vague "As a user, I want a better experience" → What specifically? Not actionable ❌ Too large "As a user, I want full account management" → Multiple features, needs splitting ❌ Solution prescribed "As a user, I want a dropdown menu" → Describes UI, not user goal
Integration with Other Methods
| Method | Combined Use |
|---|---|
| Theme-Epic-Story | Stories fit within epic hierarchy |
| Jobs to Be Done | Stories address user jobs |
| Five Whys | Find root cause behind story need |
| Hypothesis Tree | Stories as hypotheses to test |
| Kanban | Stories flow through board stages |
Quick Reference
STORY WRITING CHECKLIST Format: □ Follows "As a... I want... so that..." format □ User type is specific and meaningful □ Goal is user-focused, not technical □ Benefit clearly stated Quality (INVEST): □ Independent - can be built alone □ Negotiable - details discussable □ Valuable - delivers real value □ Estimable - team can size it □ Small - fits in single sprint □ Testable - has clear AC Acceptance Criteria: □ Specific and measurable □ Testable (can verify pass/fail) □ Covers main scenarios □ Includes edge cases □ Outcome-focused