STORY-{ID}: {Title}

Scrum Master로서 **스토리 생성** 워크플로우를 실행합니다.

Scrum Master로서 스토리 생성 워크플로우를 실행합니다.

Workflow Overview#

Goal: Create detailed user story document for a single story

Phase: 4 - Implementation (Story Definition)

Agent: Scrum Master

Inputs: Story ID or description, sprint plan (if exists)

Output: docs/stories/STORY-{ID}.md

Duration: 10-20 minutes per story

When to use: When you want detailed story documentation before implementation

Pre-Flight#

Load context per helpers.md#Combined-Config-Load
Check sprint status per helpers.md#Load-Sprint-Status
Load sprint plan (if exists): docs/sprint-plan-*.md
Get story input:
- If user provides STORY-ID: Find it in sprint plan
- If user provides description: Create new story
Load ZenHub context per helpers.md#Load-ZenHub-Context
Check epic ZenHub ID: If story's epic has zh_epic_id in sprint status, store for parent linking

Story Creation Process#

Use TodoWrite to track: Pre-flight → Gather Info → Define Story → Acceptance Criteria → Technical Details → Dependencies → Generate → Update Status → ZenHub Sync

Approach: Organized, pragmatic, detail-oriented.

Part 1: Story Identification#

If story ID provided (e.g., "STORY-001"):

Load sprint plan
Find story by ID
Extract existing details (title, epic, points, basic description)
Expand with full details

If description provided:

Generate next story ID (check sprint status for last ID)
Ask user for epic/category
Ask user for priority
Proceed with story creation

Part 2: Define User Story#

Core user story format:

As a {user type}
I want to {capability}
So that {benefit}

Ask user (if not from sprint plan):

"Let's define the user story. Who is the user and what do they want to accomplish?"

Good user stories:

As a customer, I want to view my order history, so that I can track past purchases
As an administrator, I want to manage user roles, so that I can control access permissions
As a registered user, I want to reset my password, so that I can regain access if I forget it

Bad user stories:

"Implement user login" (not user-focused)
"Create database table" (too technical, no user value)
"Fix bug in checkout" (that's a bug fix, not a story)

Store as: ``

Part 3: Detailed Description#

Expand on the user story:

Ask: "What's the detailed context and scope for this story?"

Include:

Background: Why is this needed? What problem does it solve?
Scope: What's included? What's explicitly out of scope?
User flow: Step-by-step what the user does

Example:

## Description

### Background
Currently, users cannot recover their accounts if they forget passwords. This leads to support tickets and frustrated users. This story implements a self-service password reset flow.

### Scope
**In scope:**
- Email-based password reset link
- Secure token generation (expires in 1 hour)
- Password strength validation
- Success confirmation

**Out of scope:**
- SMS-based reset (future enhancement)
- Password history tracking
- Account recovery via security questions

### User Flow
1. User clicks "Forgot Password" on login page
2. User enters email address
3. System sends reset link to email
4. User clicks link (opens reset page)
5. User enters new password (with confirmation)
6. System validates password strength
7. System updates password
8. User sees success message
9. User is redirected to login

Store as: , , ``

Part 4: Acceptance Criteria#

Define testable acceptance criteria:

Format:

## Acceptance Criteria

- [ ] User can request password reset from login page
- [ ] System sends email with reset link within 1 minute
- [ ] Reset link contains secure, expiring token (1-hour validity)
- [ ] User can set new password meeting strength requirements:
  - Minimum 8 characters
  - At least one uppercase letter
  - At least one number
  - At least one special character
- [ ] System validates password confirmation matches
- [ ] Expired tokens show clear error message
- [ ] Invalid tokens show clear error message
- [ ] Successful reset shows confirmation and redirects to login
- [ ] User can login with new password immediately
- [ ] Old password no longer works after reset

Guidelines:

Each criterion should be testable (pass/fail)
Use specific, measurable language
Cover happy path and error cases
Include edge cases
Typical count: 5-12 criteria per story

Ask user: "What else must work for this story to be complete?"

Store as: ``

Part 5: Technical Notes#

Implementation guidance for developers:

Ask: "Any technical details developers should know?"

Include:

Components involved: Which parts of the codebase
APIs/endpoints: New or modified APIs
Database changes: Schema changes, migrations
Third-party services: External integrations
Edge cases: Special scenarios to handle
Security considerations: Auth, encryption, validation

Example:

## Technical Notes

### Components
- **Backend:** User service, email service, auth service
- **Frontend:** Login page, password reset pages (request, reset)
- **Database:** users table (add reset_token, reset_token_expiry columns)

### API Endpoints
- `POST /api/auth/request-password-reset` - Initiate reset
  - Input: { email }
  - Output: { success, message }
- `POST /api/auth/reset-password` - Complete reset
  - Input: { token, new_password, confirm_password }
  - Output: { success, message }
- `GET /api/auth/validate-reset-token/{token}` - Check token validity
  - Output: { valid, expired, message }

### Database Changes
```sql
ALTER TABLE users ADD COLUMN reset_token VARCHAR(255);
ALTER TABLE users ADD COLUMN reset_token_expiry TIMESTAMP;
CREATE INDEX idx_reset_token ON users(reset_token);

Security Considerations#

Generate cryptographically secure random tokens (use crypto.randomBytes)
Hash tokens before storing in database
Set token expiry to 1 hour
Rate limit reset requests (max 3 per hour per email)
Sanitize email input to prevent injection
Use HTTPS for all reset links

Edge Cases#

User requests multiple resets (invalidate previous tokens)
Reset link clicked after expiry (clear error message)
Email doesn't exist (don't reveal, generic success message)
Password doesn't meet requirements (clear validation errors)


**Store as:** ``

---

### Part 6: Story Points Estimation

**If not already estimated:**

Ask: "How complex is this story? Let's estimate story points."

**Factors to consider:**
- Business logic complexity
- Number of components to change
- Testing complexity
- Unknowns or research needed
- Dependencies on other work

**Apply Fibonacci scale:**
- 1: Trivial (1-2 hours)
- 2: Simple (2-4 hours)
- 3: Moderate (4-8 hours)
- 5: Complex (1-2 days)
- 8: Very Complex (2-3 days)
- 13: Too large (BREAK DOWN)

**For password reset example:**
- Backend API endpoints: 3 points
- Database migration: 1 point
- Frontend pages: 3 points
- Email integration: 2 points
- Testing: 2 points
- **Total: 11 points → Round to 8 (or break into 2 stories: backend 5, frontend 5)**

**Store as:** ``

---

### Part 7: Dependencies

**Identify dependencies:**

**Technical dependencies:**
- What must be done before this story?
- What other stories does this block?

**External dependencies:**
- Third-party services (email provider)
- Design assets (mockups, icons)
- Infrastructure (email sending configured)

**Example:**
```markdown
## Dependencies

**Prerequisite Stories:**
- STORY-001: User registration (must have users to reset passwords)
- STORY-002: Email service setup (need email sending capability)

**Blocked Stories:**
- None (password reset doesn't block other features)

**External Dependencies:**
- SendGrid API configured and tested
- Password strength validation library installed (zxcvbn)
- Email templates designed and approved

Store as: ``

Part 8: Definition of Done#

Standard DoD (customize as needed):

## Definition of Done

- [ ] Code implemented and committed to story branch (within epic branch hierarchy)
- [ ] Unit tests written and passing (≥80% coverage)
  - [ ] Token generation tests
  - [ ] Token validation tests
  - [ ] Password validation tests
  - [ ] Email sending tests (mocked)
- [ ] Integration tests passing
  - [ ] End-to-end reset flow test
  - [ ] Error case tests
- [ ] Code reviewed and approved (1+ reviewer)
- [ ] Documentation updated
  - [ ] API documentation
  - [ ] User guide section
- [ ] Security review completed
- [ ] Acceptance criteria validated (all ✓)
- [ ] Deployed to staging environment
- [ ] Manual testing completed
- [ ] Product owner approval
- [ ] Merged to main branch
- [ ] Deployed to production

Store as: ``

Part 9: Additional Sections (Optional)#

UI/UX Notes (if applicable):

Wireframes or mockups
Design specifications
Accessibility requirements

Testing Strategy:

Unit test scenarios
Integration test scenarios
Manual test checklist

Rollout Plan (if needed):

Feature flags
Phased rollout
Rollback plan

Part 9.5: Sub-task Decomposition (Optional)#

Skip if zh_sub_tasks_enabled = false or story points < sub_tasks.min_story_points.

If sub-tasks are enabled and story is large enough:

Auto-generate sub-tasks per helpers.md#Auto-Generate-Sub-tasks:
- Parse the story's acceptance criteria → validation sub-tasks
- Parse technical notes → implementation sub-tasks
- Parse definition of done → test sub-tasks

Present sub-task preview:

Suggested Sub-tasks for STORY-{ID} ({points} pts):

Implementation:
  1. {implementation_task_1}
  2. {implementation_task_2}

Validation:
  3. Validate: {AC_1_summary}
  4. Validate: {AC_2_summary}

Testing:
  5. Test: {test_scenario}

Total: {count} sub-tasks

Add these sub-tasks? (y/n/edit)

If approved:
- Store sub-tasks in story document under "## Sub-tasks" section
- Sub-tasks will be synced to ZenHub in Part 10 (if zh_available)

Add to story document:

## Sub-tasks

| # | Title | Type | Status |
|---|-------|------|--------|
| 1 | {title} | Implementation | Not Started |
| 2 | {title} | Validation | Not Started |
| 3 | {title} | Test | Not Started |

Generate Story Document#

Create story document:

# STORY-{ID}: {Title}

**Epic:** {Epic ID/name}
**Priority:** {Must Have | Should Have | Could Have}
**Story Points:** {points}
**Status:** Not Started
**Assigned To:** Unassigned
**Created:** {date}
**Sprint:** {sprint_number}

---

## User Story

As a {user type}
I want to {capability}
So that {benefit}

---

## Description



---

## Scope



---

## User Flow



---

## Acceptance Criteria



---

## Technical Notes



---

## Dependencies



---

## Definition of Done



---

## Story Points Breakdown

- **Backend:** {points} points
- **Frontend:** {points} points
- **Testing:** {points} points
- **Total:** {total} points

**Rationale:** {why this estimate}

---

## Additional Notes

{Any other relevant information}

---

## Progress Tracking

**Status History:**
- {date}: Created by {user}
- {date}: Started by {developer}
- {date}: Code review by {reviewer}
- {date}: Completed

**Actual Effort:** TBD (will be filled during/after implementation)

---

**This story was created using BMAD Method v6 - Phase 4 (Implementation Planning)**

Save document:

Path: docs/stories/STORY-{ID}.md
Use Write tool

Update Sprint Status#

If sprint status exists:

Per helpers.md#Update-Sprint-Status:

Find story in sprint status YAML
Update story status to "defined"
Add story document path
Save status file

If story is new:

Add to current sprint in sprint status
Increment story count
Add points to sprint total

Part 10: Sync to ZenHub#

Skip this part if zh_available = false.

Build story body for GitHub issue from the generated story document:
- Include: User Story, Description, Acceptance Criteria, Technical Notes
- Format as markdown
Call helpers.md#Sync-Story-to-ZenHub with:
- story_title: Story title (from Part 1)
- story_body: Compiled markdown content
- story_points: Estimated points (from Part 6)
- zh_epic_id: Parent epic's ZenHub ID (from Pre-Flight step 6, if available)
- sprint_id: zh_active_sprint.id (if story belongs to current sprint)
- pipeline_id: zh_pipelines["Sprint Backlog"]
Call helpers.md#Store-ZenHub-Cross-Reference:
- Update story document with ZenHub link
- Update sprint-status.yaml with zh_issue_id, zh_issue_number, zh_issue_url
Log result: ✓ Story synced to ZenHub: #{issue_number} ({url})
Sync Sub-tasks (if zh_sub_tasks_enabled and sub-tasks were created in Part 9.5):
For each sub-task from Part 9.5: a. Generate sub-task body per helpers.md#Generate-Sub-task-Body b. Call helpers.md#Sync-Sub-task-to-ZenHub:
- sub_task_title, sub_task_body
- zh_story_id (parent, from step 2 above) c. Store zh_sub_task_id, issue number, URL d. Log: ✓ Sub-task synced: #{sub_issue_number} (parent: #{story_issue_number})

Update sprint-status.yaml with sub_tasks array:

sub_tasks:
  - id: "sub-task-001"
    title: "{title}"
    status: "not-started"
    zh_issue_id: "{zh_sub_task_id}"
    zh_issue_number: {number}
    zh_issue_url: "{url}"
    zh_pipeline: "Sprint Backlog"

Display Summary#

Show summary:

✓ Story Created!

STORY-{ID}: {Title}
Epic: {epic}
Priority: {priority}
Story Points: {points}

Acceptance Criteria: {count}
Dependencies: {count}

Document: docs/stories/STORY-{ID}.md
Branch (planned): story/STORY-{ID}-{slug}
Epic Branch: epic/EPIC-{number}-{slug}

ZenHub: #{issue_number} ({url})  (if zh_available)
Pipeline: Sprint Backlog
Sprint: {sprint_name}
Sub-tasks: {count} synced  (if sub-tasks created)

Ready for implementation!
Run /dev-story STORY-{ID} to begin development.

Story documented! Next steps:

Option 1: Implement the story
Run /dev-story STORY-{ID}

Option 2: Create another story
Run /create-story STORY-{next-ID}

Option 3: Check sprint status
Run /sprint-status

Helper References#

Load config: helpers.md#Combined-Config-Load
Load sprint status: helpers.md#Load-Sprint-Status
Update sprint status: helpers.md#Update-Sprint-Status
Save document: helpers.md#Save-Output-Document
ZenHub context: helpers.md#Load-ZenHub-Context
Sync story: helpers.md#Sync-Story-to-ZenHub
Sync sub-task: helpers.md#Sync-Sub-task-to-ZenHub
Auto-generate sub-tasks: helpers.md#Auto-Generate-Sub-tasks
Generate story body: helpers.md#Generate-Story-Body
Generate sub-task body: helpers.md#Generate-Sub-task-Body
Store xref: helpers.md#Store-ZenHub-Cross-Reference

Tips for Good Stories#

INVEST criteria:

Independent: Can be developed independently
Negotiable: Details can be discussed
Valuable: Delivers user value
Estimable: Team can estimate effort
Small: Fits in a sprint
Testable: Has clear acceptance criteria

Common mistakes to avoid:

Too technical (focus on user value, not implementation)
Too large (break down >8 point stories)
No acceptance criteria (how do you know it's done?)
Missing dependencies (blocks progress)
Vague description (leads to confusion)

Notes for LLMs#

Maintain approach (organized, pragmatic)
Use TodoWrite to track 8 story creation steps
Ensure acceptance criteria are specific and testable
Include technical details to guide implementation
Apply INVEST criteria
Reference helpers.md for status operations
Generate complete, production-ready story documents
Hand off to Developer for implementation
After generating the story document locally, sync to ZenHub (Part 10) if zh_available
Use createGitHubIssue with [Story] prefix per workspace convention
Link story to parent epic via zh_epic_id if available
Store ZenHub cross-reference in both story doc and sprint-status.yaml
Sub-task decomposition (Part 9.5) is optional: only for stories >= min_story_points when zh_sub_tasks_enabled
Sub-tasks are synced to ZenHub after the parent story (they need zh_story_id as parent)
Use Generate Body helpers for consistent issue formatting
If ZenHub sync fails, warn and continue — local document is still valid

Remember: A well-defined story = smooth development. Vague stories = confusion, rework, and delays.

STORY-{ID}: {Title}

Workflow Overview#

Pre-Flight#

Story Creation Process#

Part 1: Story Identification#

Part 2: Define User Story#

Part 3: Detailed Description#

Part 4: Acceptance Criteria#

Part 5: Technical Notes#

Security Considerations#

Edge Cases#

Part 8: Definition of Done#

Part 9: Additional Sections (Optional)#

Part 9.5: Sub-task Decomposition (Optional)#

Generate Story Document#

Update Sprint Status#

Part 10: Sync to ZenHub#

Display Summary#

Recommend Next Steps#

Helper References#

Tips for Good Stories#

Notes for LLMs#