| name | user-story |
| description | This skill decomposes product requirements into executable user stories. Based on humanity's three eternal minimal stories (Light, Dark, Grey), it organizes and evaluates story quality, helping create story collections, write user stories, and plan implementation iterations. |
| depends | ["real.md","cog.md","spec-product-requirements.md"] |
| generates | ["spec-user-story.md"] |
User Stories (Based on Three Minimal Stories)
Overview
This skill transforms product requirements into executable user stories. We adopt traditional user story format but use humanity's three eternal minimal stories (Light, Dark, Grey) as an organizing and evaluation framework, ensuring stories are both human-centered and implementation-ready.
Core Philosophy: All complex narratives originate from three minimal stories—Light (bad to good), Dark (good to bad), Grey (cyclical). Good user stories should let users experience these eternal patterns.
Note for AI Agents: This skill generates specification documents for AI/Agent consumption (especially Claude Code), ensuring story implementation has clear user value and testability.
Prerequisites
Before using this skill, ensure the following foundation documents exist:
- real.md - Reality Constraints Document
- cog.md - Cognitive Model Document
- spec-product-requirements.md - Product Requirements Document
If these files do not exist, invoke the corresponding skills to create them first.
Pre-execution Checklist
[ ] real.md exists in project root or .42cog directory
[ ] cog.md exists in project root or .42cog directory
[ ] spec-product-requirements.md exists and contains core requirements
[ ] User types and their goals have been identified
[ ] Product's core value proposition is understood
Context Loading
From cog.md, extract:
- User Types: Different user roles
- User Goals: What each user type wants to achieve
- User Capabilities: Skills and limitations users possess
From spec-product-requirements.md, extract:
- Core Features: Main features the product provides
- Feature Priority: Which features are most important
- User Value: Value each feature brings to users
From real.md, extract:
- Boundary Conditions: Boundaries for user stories
- Safety Constraints: Security rules that must be followed
- Technical Constraints: Technical limitations for implementation
Three Minimal Stories Framework
Story Archetypes
All human narratives can be reduced to three minimal stories:
| Story Type | Pattern | Emotional Arc | User Experience | Product Application |
|---|
| Light Story | Bad to Good | ↗️ Rising | Problem solving, goal achievement | Registration → Successful use |
| Dark Story | Good to Bad | ↘️ Falling | Encountering difficulties, needing help | Error handling, exception alerts |
| Grey Story | Cyclical | 🔄 Fluctuating | Continuous use, habit formation | Daily operations, repetitive tasks |
Application in User Stories
Light Stories (Growth Type):
- User goes from "cannot do X" to "can do X"
- From "difficult" to "easy"
- From "don't understand" to "understand"
- Examples: New user registration, first successful operation, skill improvement
Dark Stories (Challenge Type):
- User encounters errors or obstacles
- System helps user identify and resolve problems
- From "normal" to "abnormal" to "recovery"
- Examples: Form validation failure, insufficient permissions, data loss warning
Grey Stories (Routine Type):
- User's repetitive operations
- Need to optimize efficiency and experience
- From "unfamiliar" to "proficient" to "automated"
- Examples: Daily login, routine queries, batch operations
Story Hierarchy
Minimal Story (MS)
A minimal story is an indivisible unit of user value that can be completed within one iteration.
Characteristics:
- Independent and complete user value
- Can be implemented in 1-3 days
- Has clear completion criteria
- User can immediately perceive value
Numbering Convention: MS-[Type]-[Number]
- MS-L-01: Light Story 1
- MS-D-01: Dark Story 1
- MS-G-01: Grey Story 1
Complex Story (CS)
A complex story is a combination of multiple minimal stories, forming a complete user journey.
Characteristics:
- Contains 3-8 minimal stories
- Spans multiple iterations
- Forms a complete functional module
- Usually mixes multiple story types
Numbering Convention: CS-[Number]
- CS-01: User Account Management
- CS-02: Content Creation Flow
When to Use This Skill
- Decompose product requirements into executable stories
- Create backlog for agile development
- Define acceptance criteria for features
- Plan implementation iterations
- Communicate user value to developers
Process
Phase 1: Identify Complex Stories
Extract main user journeys from product requirements to form complex stories.
Complex Story Template:
## Complex Story: [CS-XX] [Story Name]
**Description:** [Complete user journey this story covers]
**User Type:** [Primary user role]
**Core Value:** [Main value brought to users]
**Story Type Distribution:**
- Light Stories: X (user growth)
- Dark Stories: Y (problem handling)
- Grey Stories: Z (daily use)
**Included Minimal Stories:**
- MS-L-01: Minimal Story 1
- MS-L-02: Minimal Story 2
- MS-D-01: Minimal Story 3
- MS-G-01: Minimal Story 4
**User Journey:**
[Starting Point] → [Key Node 1] → [Key Node 2] → [End Point]
Standard Complex Story Categories:
| Complex Story | Description | Typical MS Count |
|---|
| CS-01: User Onboarding | Registration, login, first use | 3-5 |
| CS-02: Core Features | Product's main value features | 5-8 |
| CS-03: User Configuration | Personalization settings | 2-4 |
| CS-04: Admin Features | Administrator operations | 3-6 |
Phase 2: Write Minimal Stories
Minimal Story Format:
## Minimal Story: [MS-X-XX] [Title]
**Complex Story:** [CS-XX]
**Story Type:** Light/Dark/Grey
**Priority:** P0/P1/P2
**Story Points:** 1/2/3/5/8
### User Story
As a [user type],
I want to [do something],
So that [achieve goal/gain value].
### Story Evaluation (Based on Three Minimal Stories)
**If Light Story (bad to good):**
- **Starting State**: User's current predicament or limitation
- **Turning Point**: Key capability system provides
- **End State**: Goal achieved or capability gained by user
- **Emotional Experience**: From confusion/restricted → understanding/freedom
**If Dark Story (good to bad):**
- **Starting State**: User's normal operational state
- **Turning Point**: Problem or error that appears
- **End State**: System helps user identify and recover
- **Emotional Experience**: From smooth → blocked → helped
**If Grey Story (cyclical):**
- **Cycle Pattern**: Operations user repeatedly performs
- **Optimization Point**: How to make repetition more efficient
- **Habit Formation**: How to go from unfamiliar to proficient
- **Emotional Experience**: From effortful → easy → automated
### Acceptance Criteria
- AC1: [Testable criterion 1]
- AC2: [Testable criterion 2]
- AC3: [Testable criterion 3]
### User-Perceivable Changes
- : [What user sees/feels]
: [What action user performs]
: [What change user sees/feels]
[Constraint 1]
[Constraint 2]
: [Prerequisite stories]
: [Subsequent stories]
Story Writing Guidelines:
| Element | Good Example | Bad Example |
|---|
| User Type | "Newly registered user" | "User" |
| Want to Do | "Create first project" | "Use system" |
| Achieve Goal | "Start managing my tasks" | "Be able to work" |
| Acceptance Criteria | "Project created successfully and displayed in list" | "Feature works" |
INVEST Principles (Maintaining Traditional Best Practices):
- Independent: Can be developed and tested independently
- Negotiable: Details can be discussed and adjusted
- Valuable: Brings clear value to users
- Estimable: Work effort can be estimated
- Small: Can be completed within one iteration
- Testable: Has clear acceptance criteria
Phase 3: Define Acceptance Criteria
Each minimal story needs 3-5 testable acceptance criteria.
Acceptance Criteria Formats:
Format 1: Scenario-Based
### Acceptance Criteria
**Scenario 1: Normal Flow**
- Given: [Precondition]
- When: [User action]
- Then: [Expected result]
**Scenario 2: Exception Handling**
- Given: [Exception condition]
- When: [User action]
- Then: [System response]
Format 2: Checklist-Based
### Acceptance Criteria
- [ ] User can see [UI element]
- [ ] After user clicks [button], system [performs action]
- [ ] System displays [feedback message]
- [ ] Data saved to [storage location]
- [ ] User can [subsequent operation]
Criteria Quality Check:
Phase 4: Create Story Map
Story maps visualize user journeys and determine story priorities.
Story Map Structure:
User Journey: Onboarding → Using → Mastering → Spreading
Iteration 1 (MVP):
├── CS-01: User Onboarding
│ ├── MS-L-01: Quick Registration (Light)
│ │ └── From "no account" → "has account"
│ ├── MS-L-02: First Login (Light)
│ │ └── From "outside" → "inside"
│ └── MS-D-01: Login Failure Handling (Dark)
│ └── From "smooth" → "blocked" → "recovered"
├── CS-02: Core Features
│ ├── MS-L-03: Create First Project (Light)
│ └── MS-L-04: Complete First Task (Light)
Iteration 2:
├── CS-02: Core Features (continued)
│ ├── MS-G-01: View Project List (Grey)
│ └── MS-G-02: Edit Task (Grey)
├── CS-03: User Configuration
│ └── MS-L-05: Personalization Settings (Light)
Iteration 3:
├── CS-04: Advanced Features
└── CS-05: Collaboration Features
Prioritize by Story Type:
| Priority | Story Type Mix | Rationale | Decision |
|---|
| P0 | Primarily Light | Users need to see value quickly | Implement first |
| P1 | Light + Dark | Basic features + error handling | Iteration 2 |
| P2 | Primarily Grey | Optimize daily use experience | Later optimization |
Phase 5: Implementation Planning
Implementation Plan Template:
## Iteration [N] Plan
**Goal:** [Core goal of this iteration]
**Duration:** [2 weeks]
**Complex Stories:** [CS-XX, CS-YY]
### Minimal Story List
| Story ID | Title | Type | Story Points | Owner |
|----------|-------|------|--------------|-------|
| MS-L-01 | Quick Registration | Light | 3 | Zhang San |
| MS-L-02 | First Login | Light | 2 | Li Si |
| MS-D-01 | Login Failure | Dark | 2 | Wang Wu |
### Story Type Distribution
- Light Stories: 5 (60%) - Main value delivery
- Dark Stories: 2 (25%) - Error handling
- Grey Stories: 1 (15%) - Experience optimization
### Expected User Value
After this iteration, users can:
1. [Completed user journey 1]
2. [Completed user journey 2]
3. [Completed user journey 3]
### Dependencies
- **External**: [API access, design resources]
- **Internal**: [Other team deliverables]
### Risks
- Risk 1: [Description]
- Mitigation: [Response measures]
Output Template
User Story Document
# User Stories: [Product Name]
## Complex Story Overview
| Complex Story | MS Count | Priority | Story Type Distribution |
|--------------|----------|----------|------------------------|
| CS-01 | 5 | P0 | Light 3, Dark 1, Grey 1 |
| CS-02 | 8 | P0 | Light 4, Dark 2, Grey 2 |
## Grouped by Complex Story
### CS-01: [Name]
#### MS-L-01: [Title]
[Complete minimal story including story evaluation and acceptance criteria]
#### MS-D-01: [Title]
[Complete minimal story including story evaluation and acceptance criteria]
## Story Map
[Visualized user journey and iteration breakdown]
## Implementation Recommendations
[Implementation plan broken down by iterations 1, 2, 3]
## Testing Guide
[How to verify completion criteria for each story]
Quality Checklist
Integration with Other Skills
| Skill | Relationship |
|---|
| product-requirements | Input: Requirements transformed into stories |
| system-architecture | Output: Stories influence architecture design |
| ui-design | Output: Stories drive interface design |
| coding | Output: Stories become development tasks |
| quality-assurance | Output: Acceptance criteria become test cases |
Appendix: Deep Understanding of Three Minimal Stories
Why These Three Stories?
Cognitive science research shows that the human brain is naturally sensitive to these three patterns:
-
Light Story (Progress Narrative)
- Activates brain's reward system
- Produces dopamine, bringing pleasure
- Users most easily remember and spread
- Product examples: First success, skill improvement, problem solving
-
Dark Story (Crisis Narrative)
- Activates brain's alertness system
- Produces focused attention, promotes learning
- Helps users establish sense of security
- Product examples: Error alerts, risk warnings, recovery mechanisms
-
Grey Story (Cyclical Narrative)
- Activates brain's habit system
- Produces automation, reduces cognitive load
- Helps users form usage habits
- Product examples: Daily operations, repetitive tasks, batch processing
Golden Ratio of Story Types
According to user experience research, the optimal story type distribution is:
| Product Stage | Light | Dark | Grey |
|---|
| MVP Stage | 70% | 20% | 10% |
| Growth Stage | 50% | 30% | 20% |
| Mature Stage | 40% | 20% | 40% |
Rationale:
- Early stage needs to quickly demonstrate value (primarily Light)
- Mid stage needs to build trust (increase Dark stories)
- Later stage needs to optimize efficiency (increase Grey stories)
Simplified Application of Affordance Thinking
While we don't use complex affordance terminology, the core ideas are retained:
| Affordance Concept | Simplified Expression |
|---|
| Affordance | What user can do |
| Perception Channel | How user knows they can do it |
| Action | Operation user performs |
| Feedback | Result user sees |
Reflected in Acceptance Criteria:
- [ ] User can see [button] (perception)
- [ ] After user clicks [button] (action)
- [ ] System displays [result] (feedback)
Last Updated: 2025-12-06
Document Version: v3.1 (Based on Three Minimal Stories)
Maintainer: 42COG Team
