pm-story-write

Generate user stories with Given/When/Then acceptance criteria following INVEST principles.

Purpose

The /pm-story-write skill generates production-ready user stories in Connextra format ("As a [role], I want [action], so that [value]") with Gherkin Given/When/Then acceptance criteria. It enforces INVEST quality standards, provides systematic edge case coverage, and validates stories against Definition of Ready criteria.

Command

/pm-story-write [input]

Input Formats

The skill accepts four input formats:

1. Structured Format

/pm-story-write "[feature]" "[persona]" "[goal]"

Example:

/pm-story-write "bulk export feature" "system administrator" "analyze usage data offline"

2. Narrative Format

Provide a full feature description in natural language:

/pm-story-write "As an admin I need to export user data to Excel for compliance reporting"

The skill will extract feature, persona, and goal using the 5 Whys technique.

3. Jira Context (requires MCP)

Provide a Jira epic or story ID:

/pm-story-write PROJ-123

The skill will attempt to read context from Jira via MCP and use it to inform the story.

4. Screenshot Path

Provide design screenshots showing the UI element the story refers to. Images are embedded as rendered markdown links in the Context section.

Output

Creates a story file at:

jaan-to/outputs/pm/stories/{slug}/stories.md

Where {slug} is generated from the story title (lowercase, hyphens, max 50 chars).

Workflow

The skill follows a two-phase workflow with a mandatory approval checkpoint:

Phase 1: Analysis (Read-Only)

Parse Input - Extracts feature, persona, and goal from any input format
Gather Context - Asks up to 5 clarifying questions (only if needed):
- Persona context (avoid generic "user")
- Business value (applies 5 Whys technique)
- Dependencies
- Out-of-scope items
- Related epic/stories
Map Edge Cases - Detects applicable categories from 10 standard patterns:
- Empty States, Boundary Conditions, Permission Failures, Concurrency
- Network Failures, Invalid Input, State Transitions, Internationalization
- Timeout/Expiry, Bulk Operations
Plan Story Structure - Drafts persona/capability/value + 3-7 acceptance criteria scenarios
HARD STOP - Presents plan and waits for explicit approval

Phase 2: Generation (Write Phase)

Generate Content - Creates 8-section story using template
Quality Check - Validates against three checkpoints:
- INVEST Compliance (6 criteria)
- AC Testability (observable outcomes)
- Definition of Ready (10 items)
Splitting Detection - Suggests patterns if story is too large (>7 ACs or >8 points)
Preview & Approval - Shows complete story, waits for approval
Write Output - Saves to file system
Export Formats - Provides Jira CSV and Linear JSON for easy import
Capture Feedback - Offers to fix now, learn for future, or both

Story Format

Generated stories follow this 8-section structure:

1. YAML Frontmatter

---
story_id: US-XXX
epic: "Epic Name"
title: "Verb-First Title"
priority: high
status: draft
estimate: TBD
labels: [label1, label2]
created: 2026-02-02
last_updated: 2026-02-02
---

2. Context Paragraph

2-4 sentences explaining WHY this story exists (business drivers, metrics, user research).

3. Story Statement (Connextra Format)

**As a** [specific persona with context]
**I want to** [single capability]
**So that** [business value]

4. Acceptance Criteria (Gherkin)

3-7 scenarios covering happy path + edge cases:

### Scenario 1: Happy Path Name
```gherkin
Given [precondition state]
When [user action]
Then [observable outcome]
  And [additional outcome]

Scenario 2: Edge Case Name

Given [precondition]
When [action]
Then [outcome]

### 5. Scope
- **In-Scope**: Explicit deliverables
- **Out-of-Scope**: Deferred items with references

### 6. Dependencies
Table format with dependency, type, status, and owner.

### 7. Technical Notes
Brief implementation hints (API contracts, performance requirements).

### 8. Open Questions
Unresolved items with decision owners and deadlines.

### 9. Definition of Done
Standard checklist for completion criteria.

---

## Quality Gates

### INVEST Compliance (Checkpoint 1)

Every story is validated against all 6 INVEST criteria:

| Criterion | Validates |
|-----------|-----------|
| **Independent** | Can ship without other stories |
| **Negotiable** | Describes WHAT not HOW |
| **Valuable** | Delivers user/business value |
| **Estimable** | Team can understand and size |
| **Small** | Fits in one sprint (≤8 points) |
| **Testable** | Has clear pass/fail criteria |

### AC Testability (Checkpoint 2)

- Every "Then" clause has observable outcome
- No subjective criteria ("good UX", "fast")
- Quantified where applicable ("<2 seconds", "3 steps")

### Definition of Ready (Checkpoint 3)

10-item checklist including:
- Connextra format ✓
- Business value articulated ✓
- Specific persona (not "user") ✓
- 3-7 testable acceptance criteria ✓
- Edge cases covered ✓
- INVEST criteria pass ✓
- Sprint-sized ✓
- Dependencies identified ✓

---

## Edge Case Coverage

The skill auto-detects applicable edge case categories based on feature type:

### Detection Matrix

| Feature Type | Auto-Detected Categories | Min ACs |
|--------------|-------------------------|---------|
| CRUD operations | Empty States, Invalid Input, Concurrency, Boundary Conditions | 4 |
| API integration | Network Failures, Timeout/Expiry, Invalid Input | 4 |
| Multi-step workflow | State Transitions, Timeout/Expiry, Empty States | 4 |
| User input forms | Invalid Input, Boundary Conditions, Empty States | 4 |
| Multi-user/roles | Permission Failures, Concurrency | 3 |
| Data processing | Bulk Operations, Boundary Conditions, Timeout/Expiry | 4 |
| International app | Internationalization, Boundary Conditions | 3 |
| Real-time features | Concurrency, Network Failures, State Transitions | 4 |

All stories require: Happy path + at least 1 error handling + empty state (if data-driven)

---

## Story Splitting

If the story is too large (>7 acceptance criteria or >8 story points), the skill suggests splitting using one of 6 proven patterns:

1. **Workflow Steps** - Split multi-step processes into stages
2. **CRUD Operations** - Separate Create/Read/Update/Delete
3. **Happy Path First** - Core success now, edge cases later
4. **Data Variations** - Split by data types or complexity
5. **Spike + Implementation** - Research first, then implement
6. **Cross-Cutting Concerns** - Defer performance/security/scale

---

## Export Formats

After creating a story, the skill provides ready-to-use export formats:

### Jira CSV Import
```csv
Summary,Description,Issue Type,Priority,Story Points,Epic Link,Labels
"Story Title","Full story content","Story","High",TBD,"EPIC-123","label1,label2"

Linear GraphQL

{
  "input": {
    "title": "Story Title",
    "description": "Full story markdown",
    "priority": 2,
    "estimate": null,
    "labelIds": ["label-uuid"]
  }
}

Examples

Example 1: Password Reset Feature

Input:

/pm-story-write "password reset" "web app user" "regain access if forgotten"

Generated Story:

Persona: Web app user who forgot their password
Feature: Password reset via email link
Value: Regain account access without support intervention
ACs: 5 scenarios covering happy path, invalid email, expired link, password requirements, network timeout
Edge Cases: Empty States, Invalid Input, Network Failures, Timeout/Expiry
Output: jaan-to/outputs/pm/stories/password-reset/stories.md

Example 2: Bulk Data Export

Input:

/pm-story-write "bulk export feature" "system administrator" "analyze usage data offline"

Generated Story:

Persona: System administrator managing large datasets
Feature: Export user data to CSV/Excel
Value: Perform offline analysis and compliance reporting
ACs: 6 scenarios covering export initiation, format selection, large files, progress tracking, download, empty state
Edge Cases: Empty States, Bulk Operations, Timeout/Expiry, Invalid Input
Output: jaan-to/outputs/pm/stories/bulk-data-export/stories.md

Common Use Cases

Use Case	Input Format	Expected ACs	Edge Cases
User authentication	Structured	4-5	Permission Failures, Invalid Input, Network Failures
Data export	Structured	5-6	Bulk Operations, Boundary Conditions, Timeout/Expiry
Multi-step checkout	Narrative	6-7	State Transitions, Network Failures, Empty States
Role-based access	Structured	4-5	Permission Failures, Concurrency
Search functionality	Structured	5-6	Empty States, Boundary Conditions, Invalid Input
Form validation	Structured	4-5	Invalid Input, Boundary Conditions, Empty States

Tips

Best Practices

Be specific with personas - "Busy parent managing family schedule" is better than "user"
State genuine value - Apply 5 Whys to avoid feature-focused "so that" clauses
Include out-of-scope - Prevents scope creep and documents decisions
Leverage Jira context - Provides consistency with existing stories and team conventions
Accept splitting suggestions - Stories >7 ACs rarely fit in a sprint

Common Mistakes to Avoid

Using generic "As a user" without context
Feature-focused value: "so I can export data" (output) vs "so I can reduce churn" (outcome)
Implementation details in ACs: "Use Redux" (implementation) vs "Cart persists" (behavior)
Skipping Out-of-Scope section
Subjective ACs: "Intuitive UX" (not testable) vs "Completes in ≤3 steps" (testable)
Missing empty state handling

Feedback Capture

After generating a story, the skill offers three feedback options:

Fix now - Apply feedback to current story immediately
Learn - Save lesson via /learn-add for future improvements
Both - Fix current story AND save lesson

This continuous learning system improves story quality over time.

Research: jaan-to/outputs/research/45-pm-insights-synthesis.md - Comprehensive framework
PRD Generation: /pm-prd-write - Create full PRDs with success metrics
Learning: /learn-add - Add lessons to improve skill execution

Generated by jaan.to | 2026-02-02

Purpose​

Command​

Input Formats​

1. Structured Format​

2. Narrative Format​

3. Jira Context (requires MCP)​

4. Screenshot Path​

Output​

Workflow​

Phase 1: Analysis (Read-Only)​

Phase 2: Generation (Write Phase)​

Story Format​

1. YAML Frontmatter​

2. Context Paragraph​

3. Story Statement (Connextra Format)​

4. Acceptance Criteria (Gherkin)​

Scenario 2: Edge Case Name​

Linear GraphQL​

Examples​

Example 1: Password Reset Feature​

Example 2: Bulk Data Export​

Common Use Cases​

Tips​

Best Practices​

Common Mistakes to Avoid​

Feedback Capture​

Related​