Skip to main content

Production-Ready PM Story-Write Skill: A Comprehensive Framework

User stories built right save teams hundreds of hours. This research document provides everything needed to implement a production-ready skill for writing user stories with Given/When/Then acceptance criteria. The framework combines Scrum conventions with Shape Up pragmatism, delivering consistent, high-quality stories across SaaS, e-commerce, fintech, and mobile domains. Key findings include a complete template structure with 8 essential sections, 6 proven splitting patterns, 10+ edge case categories, and tool-specific import schemas for Jira and Linear.

1. Executive Summary​

Critical Decisions Made​

The pm:story-write skill adopts a hybrid Scrum+Shape Up approach that balances structure with pragmatism:

  • Primary format: Connextra template ("As a [role], I want [action], so that [value]")
  • Acceptance criteria: Gherkin Given/When/Then syntax for testability
  • Quality standard: INVEST criteria (Independent, Negotiable, Valuable, Estimable, Small, Testable)
  • Scope management: Shape Up "appetite framing" with explicit In-Scope/Out-of-Scope sections
  • Output format: Markdown with YAML frontmatter for tool portability

Recommended Story Format​

---
epic: "Feature Epic"
priority: high
estimate: 5
labels: [backend, mvp]
status: ready
---

## US-001: [Verb-First Title]

### Story Statement
**As a** [specific persona]
**I want to** [action/capability]
**So that** [measurable business value]

### Acceptance Criteria
```gherkin
Given [precondition]
When [action]
Then [observable outcome]

Scope​

In-Scope: [Explicit boundaries] Out-of-Scope: [Deferred items with story references]

Dependencies​

  • [Blocking items listed]

### Key Quality Gates

Stories must pass three validation checkpoints:

1. **INVEST compliance** — Each criterion verified by checklist
2. **AC testability** — Every criterion converts to pass/fail test
3. **Definition of Ready** — 10-item checklist before sprint entry

---

## 2. Standards Reference

### Professional Standards Foundation

The industry has converged on several foundational standards for user story writing, though notably **user stories are not prescribed in the Scrum Guide itself**—they represent a complementary practice that has become ubiquitous.

**Scrum Alliance and Scrum.org** position stories as Product Backlog Items (PBIs) written from the user perspective, emphasizing that stories follow Ron Jeffries' "3 Cs" concept: **Card** (the written story), **Conversation** (discussion that fleshes out details), and **Confirmation** (acceptance tests). The Agile Alliance formally defines user stories as "informal, natural language descriptions of features from the end-user perspective."

**ISO/IEC/IEEE 29148** provides the international standard for requirements engineering processes, covering requirements specification, documentation, and validation. User stories align with its concept of "stakeholder requirements specification." For regulated industries (fintech, healthcare), this standard provides traceability requirements that inform how stories should link to compliance documentation.

### The INVEST Quality Standard

Bill Wake created the INVEST mnemonic in 2003, and it remains the definitive quality checklist for user stories. Each letter represents a criterion that well-formed stories must satisfy:

| Criterion | Definition | Validation Question |
|-----------|------------|---------------------|
| **Independent** | Self-contained, not dependent on other stories | Can this ship without waiting for other stories? |
| **Negotiable** | Prompts discussion, doesn't prescribe implementation | Does it describe WHAT not HOW? |
| **Valuable** | Delivers clear benefit to users or business | Would a user pay for this or choose it? |
| **Estimable** | Clear enough for team to size | Can the team agree on relative effort? |
| **Small** | Completable in one sprint | Is it ideally 1-3 days of work? |
| **Testable** | Has clear pass/fail acceptance criteria | Can QA write tests from this? |

### Story Format Templates

**Connextra Template (Standard Format)**

Developed at Connextra UK in 2001 by Rachel Davies' team, this remains the dominant format:

As a [role/persona] I want [action/capability/feature] So that [benefit/value/outcome]


The template enforces three essential elements: the **Role** (who is the user), the **Requirement** (what they want to do), and the **Reason** (why it matters). The "so that" clause is frequently omitted by teams, which represents a critical mistake—it provides the context needed for prioritization and implementation decisions.

**Job Stories Format (Alternative)**

Developed at Intercom and refined by Alan Klement, Job Stories shift focus from persona to situation:

When [situation/context/trigger] I want to [motivation/action] So I can [expected outcome]


Job Stories work best when user types don't vary significantly, when context matters more than persona, or when taking a Jobs-to-Be-Done research approach. They prevent persona assumptions and provide clearer causality through situational context.

### BDD Gherkin Syntax Reference

Gherkin is the domain-specific language for Behavior-Driven Development, used by Cucumber, SpecFlow, and Behave. The complete keyword reference:

| Keyword | Purpose | Example |
|---------|---------|---------|
| `Feature:` | High-level software feature description | `Feature: User Authentication` |
| `Scenario:` | Concrete example illustrating a rule | `Scenario: Successful login` |
| `Given` | Initial context/preconditions | `Given I am logged in as Admin` |
| `When` | Action or event being tested | `When I click the delete button` |
| `Then` | Expected outcome/assertion | `Then I should see confirmation` |
| `And` / `But` | Additional steps of same type | `And I should receive an email` |
| `Background:` | Common setup for all scenarios | Setup steps run before each scenario |
| `Scenario Outline:` | Parameterized scenario template | For testing multiple data variations |
| `Examples:` | Data table for Scenario Outline | Provides test data combinations |

**Gherkin Best Practices:**
- **Given** describes preconditions in past tense, NOT user interaction
- **When** describes the action; should read without technology assumptions
- **Then** asserts observable outcomes; must be testable outputs
- Keep scenarios focused on **one behavior** per scenario
- Use **3-7 acceptance criteria** per story (not dozens)

---

## 3. Methodologies & Techniques

### User Story Mapping (Jeff Patton Method)

User Story Mapping organizes stories in a two-dimensional grid showing the user journey horizontally and priority vertically. Jeff Patton's methodology from "User Story Mapping: Discover the Whole Story, Build the Right Product" (O'Reilly, 2014) provides the framework most teams adopt.

**Map Structure:**
- **Backbone (top row)**: User activities representing high-level goals ("Plan a vacation")
- **Steps/Tasks**: How to complete activities ("Select destination", "Book flight")
- **Details/Stories**: Specific interactions prioritized vertically under each step

The key insight is that story maps reveal **gaps in user journeys** that flat backlogs hide. Walking through the map from different persona perspectives exposes missing steps, dependencies, and MVP boundaries. Draw horizontal lines across the map to define release slices—everything above the line ships together.

### Six Story Splitting Patterns

Effective story splitting maintains user value while reducing size. Richard Lawrence's Story Splitting Flowchart and Mike Cohn's SPIDR method provide complementary approaches:

**Pattern 1: Workflow Steps**
Split multi-step processes into individual stages.

Original: "User can publish content" Split: → "User can publish directly" → "User can publish with editor review"
→ "User can preview before publish"

*Build beginning and end first, add middle steps later.*

**Pattern 2: CRUD Operations**
Separate Create, Read, Update, Delete into independent stories.

Original: "User can manage account" Split: → "User can create account" → "User can view account details" → "User can update settings" → "User can delete account"


**Pattern 3: Happy Path First**
Implement core success scenario, defer edge cases.

Original: "User can search with filters" Split: → "User can basic search" (happy path) → "User can filter by date" → "User can handle zero results"


**Pattern 4: Data Variations**
Split by different data types or complexity levels.

Original: "User can upload documents" Split: → "User can upload PDF" → "User can upload images" → "User can upload large files (>10MB)"


**Pattern 5: Spike + Implementation**
Research first when uncertainty is high.

Original: "Integrate payment processor" Split: → "SPIKE: Evaluate Stripe vs Braintree" (timeboxed) → "Implement chosen payment processor"


**Pattern 6: Cross-Cutting Concerns**
Defer performance, security, and scalability.

Original: "Fast, secure search" Split: → "Search works correctly" → "Search responds in <2 seconds" → "Search handles 1000 concurrent users"


**The Meta-Pattern:** Find the core complexity (often human behavior), identify what there are "many of" (rules, data types, interfaces), and reduce all variations to ONE for the first slice.

### Three Amigos Sessions

Three Amigos brings together **Business** (PO/BA), **Development**, and **Testing** perspectives to examine work items before development begins.

**Session Structure:**
- **Timing**: 30-60 minutes (if longer, story is too big)
- **When**: During sprint N-1, before story enters sprint
- **Frequency**: Per story or small batch of stories

**Meeting Flow:**
1. BA presents user story, requirements, and context
2. All three perspectives question and clarify
3. Developer discusses technical approach and constraints
4. QA identifies test scenarios and edge cases
5. Story updated until deemed "Ready for Dev"
6. Estimation via planning poker
7. Tasks identified and assigned

**Outputs**: Shared understanding, refined acceptance criteria (often in Gherkin), test scenarios, technical consensus, size estimates, and "Ready" status confirmation.

### Impact Mapping for Story Derivation

Gojko Adzic's Impact Mapping connects business goals to deliverables through a four-level hierarchy:

**WHY → WHO → HOW → WHAT**
- **Why** (Goal): Measurable business objective ("Increase retention by 20%")
- **Who** (Actors): Who can help or hinder the goal
- **How** (Impacts): Behavior changes needed from actors
- **What** (Deliverables): Features/stories that create those impacts

Working backwards from goals ensures every story connects to measurable business value.

### The 5 Whys for Value Discovery

Originally from Toyota's production system, the 5 Whys technique uncovers the real value behind feature requests:

"I want to export data to Excel" Why? "So I can create reports" Why? "So I can share analysis with stakeholders" Why? "So they can make informed decisions" Why? "So we can improve customer retention"


The root value ("improve customer retention") should inform story priority and shape acceptance criteria. Teams that skip this step write stories with weak or missing "so that" clauses.

---

## 4. Transformation Process

### From Feature Request to User Stories

The transformation from [feature] + [persona] + [goal] to structured stories follows a systematic process:

**Phase 1: Understand the Feature**
- Identify stakeholders and their needs
- Set boundaries to avoid gold-plating
- Document supporting context

**Phase 2: Map Persona to Actor**
Avoid generic "As a user"—it provides no perspective value.

| ❌ Weak | ✅ Strong |
|---------|----------|
| "As a user, I want to search" | "As a first-time visitor, I want to browse categories" |
| "As a user, I want notifications" | "As a busy parent, I want push alerts for emergencies only" |

**Enhanced template with context:**

As a [persona] who [context], I want [capability] so that [value]


**Phase 3: Extract Value Statement**
Apply the 5 Whys to find genuine business value. Transform weak value statements:

| ❌ Feature-focused | ✅ Value-focused |
|-------------------|-----------------|
| "...so I can use export" | "...so I can analyze data in my spreadsheet" |
| "...so settings are saved" | "...so I don't repeat configuration each visit" |

**Phase 4: Derive Acceptance Criteria**
Start with the happy path, then systematically add edge cases using the **10 Edge Case Categories** (detailed in Section 6).

**Phase 5: Define Scope Boundaries**
Explicitly list:
- **In-Scope**: What this story delivers
- **Out-of-Scope**: What's deferred (with references to future stories)
- **Dependencies**: Blocking items and their status

### Worked Examples Across Domains

**Example A: SaaS Permission Story**

*Input*: Feature: role-based access control, Persona: system administrator, Goal: secure data

*Transformation*:

```markdown
## US-204: Implement Role-Based Access Control

### Story Statement
**As a** system administrator
**I want to** assign role-based permissions to users
**So that** users only access features appropriate to their role, ensuring data security

### Acceptance Criteria

#### Scenario 1: Admin Full Access
```gherkin
Given a user with "Admin" role logs in
When they navigate to User Management
Then they can view, create, edit, and delete all user accounts

Scenario 2: Manager Scoped Access​

Given a user with "Manager" role logs in
When they navigate to User Management
Then they can view and edit users within their department only
And they cannot create or delete users

Scenario 3: Access Denied Logging​

Given a user with "Standard" role logs in
When they attempt to access User Management
Then they see "Access Denied" message
And the access attempt is logged with user ID and timestamp

Scope​

In-Scope: Three roles (Admin, Manager, Standard), User Management CRUD, department scoping, audit logging Out-of-Scope: Custom role creation, temporary elevation, MFA for admin actions


**Example B: E-commerce Checkout Workflow**

*Input*: Feature: multi-step checkout, Persona: online shopper, Goal: complete purchase securely

```markdown
## US-089: Multi-Step Checkout Process

### Story Statement
**As an** online shopper
**I want to** complete a guided checkout process
**So that** I can review my order and securely complete my purchase

### Acceptance Criteria

#### Scenario 1: Step Navigation
```gherkin
Given I have items in my cart
When I click "Proceed to Checkout"
Then I see Step 1 (Shipping) with progress indicator showing all 4 steps

Scenario 2: Address Validation​

Given I am on the shipping step
When I enter a valid shipping address and click Continue
Then the system validates the address via API
And advances me to Step 2 (Payment)

Scenario 3: Payment Tokenization​

Given I am on the payment step
When I enter valid card details
Then the system securely tokenizes my card (no raw card data stored)
And advances to Step 3 (Review)

Scenario 4: Order Placement​

Given I am on review with valid details
When I click "Place Order"
Then the order is submitted
And I see confirmation with order number
And I receive email confirmation within 60 seconds

Scope​

In-Scope: 4-step flow, address validation, tax calculation, card tokenization, confirmation email Out-of-Scope: Guest checkout (US-092), multiple shipping addresses, PayPal/Apple Pay


**Example C: Fintech KYC Flow**

*Input*: Feature: identity verification, Persona: new customer, Goal: access full account features

```markdown
## US-301: KYC Verification Flow

### Story Statement
**As a** new fintech customer
**I want to** complete identity verification
**So that** I can access full account features while meeting regulatory requirements

### Acceptance Criteria

#### Scenario 1: Document Upload with OCR
```gherkin
Given I am uploading my ID document
When I submit a passport, driver's license, or national ID
Then the system extracts data via OCR within 10 seconds
And pre-fills my personal details for confirmation

Scenario 2: Biometric Verification​

Given I complete the biometric step
When liveness detection runs
Then the system confirms I am a real person
And my face matches the ID document with ≥98% confidence

Scenario 3: Automated Screening​

Given my information is submitted
When automated screening runs
Then my data is checked against sanctions lists and PEP databases
And screening completes within 60 seconds

Scope​

In-Scope: 4-step flow, OCR extraction, liveness detection, AML screening, status management Out-of-Scope: Enhanced Due Diligence (EDD), video KYC, business verification (KYB)

Dependencies​

  • KYC provider API (Onfido/Jumio)
  • AML screening service
  • Encrypted document storage

Notes​

GDPR compliance required for EU users. Documents retained per regulatory requirements (5-7 years).


### Handling Ambiguous Requirements

When feature descriptions are vague, apply these resolution strategies:

1. **Have Conversations** — Stories are "invitations to conversation," not specifications
2. **Add Context** — Use enhanced format: "As a [persona] who [context], I want..."
3. **Use Visual Models** — Mockups, flow diagrams, state machines clarify intent
4. **Write Concrete ACs** — Transform vague qualifiers into specifics:
   - ❌ "Fast performance" → ✅ "Responds in <2 seconds at p95"
   - ❌ "User-friendly" → ✅ "Completes in 3 steps or fewer"
5. **Break Down Further** — Ambiguity hides in compound requirements
6. **Create Spikes** — Timeboxed investigation reduces uncertainty

---

## 5. Template Recommendations

### Complete Story Template (template.md)

```markdown
---
# === Required Metadata ===
story_id: US-XXX
epic: "Epic Name or ID"
title: "Verb-First Descriptive Title"
priority: high | medium | low | critical
status: draft | ready | in_progress | done | blocked
estimate: 1 | 2 | 3 | 5 | 8 | 13  # Story points (Fibonacci)

# === Recommended Metadata ===
sprint: 14
labels: [label1, label2, label3]
assignee: "@username"
author: "@pm.username"
team: "Team Name"
component: "system-component"
created: YYYY-MM-DD
last_updated: YYYY-MM-DD

# === Optional Metadata ===
due_date: YYYY-MM-DD
blocked_by: [US-XXX, US-YYY]
acceptance_owner: "@qa.username"
version: "1.0.0"
---

# US-XXX: [Verb-First Title]

## Context
[2-4 sentences explaining WHY this story exists. Include business drivers, user research insights, and relevant metrics. No tribal knowledge—make it self-contained.]

## Story Statement

**As a** [specific persona, not generic "user"]
**I want to** [single action or capability]
**So that** [measurable business value]

## Acceptance Criteria

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

Scenario 2: [Edge Case Name]​

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

Scenario 3: [Error Handling Name]​

Given [precondition]
When [error condition occurs]
Then [user sees appropriate error message]
  And [system maintains data integrity]

[Include 3-7 scenarios covering happy path + key edge cases]

Scope​

In-Scope​

  • [Explicit item 1]
  • [Explicit item 2]
  • [Explicit item 3]

Out-of-Scope​

  • [Deferred item 1] → See US-YYY
  • [Deferred item 2] → Future epic
  • [Deferred item 3] → v2 enhancement

Dependencies​

DependencyTypeStatusOwner
[US-AAA: Prerequisite Story]Story✅ Done@team
[API/Service Name]Technical🔄 In Progress@owner
[Design Mockups]Design⏳ Pending@designer

Technical Notes​

[Implementation hints, API contracts, database changes, performance requirements. Keep brief—details belong in task breakdown.]

Resources​

Open Questions​

  • [Unresolved question needing decision] — @decider by YYYY-MM-DD
  • [Resolved question] — Decision: [outcome] (YYYY-MM-DD)

Definition of Done​

  • Acceptance criteria verified by QA
  • Code reviewed and approved
  • Unit tests written (≥80% coverage)
  • Documentation updated
  • PO acceptance received

### Fully-Filled Example

```markdown
---
story_id: US-147
epic: EPIC-32
title: "Update Email Notification Preferences"
priority: medium
status: ready
estimate: 3
sprint: 15
labels: [notifications, user-settings, backend]
assignee: "@alex.chen"
author: "@sarah.pm"
team: Platform
component: notification-service
created: 2026-01-28
last_updated: 2026-02-02
acceptance_owner: "@qa.morgan"
---

# US-147: Update Email Notification Preferences

## Context
Our Q4 2025 user survey revealed 47% of users feel they receive too many emails. Currently, users cannot customize preferences, leading to 3.2% unsubscribe rate (target: <1.5%). This story implements granular controls to improve satisfaction and reduce churn.

## Story Statement

**As a** registered user
**I want to** manage my email notification preferences
**So that** I only receive emails relevant to my needs

## Acceptance Criteria

### Scenario 1: Viewing Preferences
```gherkin
Given I am logged into my account
When I navigate to Settings > Notifications > Email
Then I see a list of all email categories with toggle switches
  And each category shows a brief description
  And my current preferences are pre-selected

Scenario 2: Updating Preferences​

Given I am on the Email Preferences page
When I toggle off "Marketing Updates" and click "Save Changes"
Then my preference is saved
  And I see success toast "Preferences updated"
  And I no longer receive marketing emails

Scenario 3: Unsubscribe All (Except Transactional)​

Given I am on the Email Preferences page
When I click "Unsubscribe from all"
Then all optional categories toggle off
  And transactional emails remain enabled (grayed out)
  And I see warning "You'll still receive account security emails"

Scope​

In-Scope​

  • Preferences UI in user settings
  • Backend API for storing/retrieving preferences
  • SendGrid integration for suppression
  • Unsubscribe link in emails → preferences page

Out-of-Scope​

  • Push notification preferences → US-152
  • SMS preferences → Future epic
  • Email frequency controls → v2

Dependencies​

DependencyTypeStatusOwner
US-140: Settings Page RedesignStory✅ Done@frontend
SendGrid Suppression APITechnical✅ Available@platform
User preferences schemaTechnical🔄 In Progress@alex.chen

Technical Notes​

  • API: PUT /api/v1/users/{userId}/preferences/email
  • Performance: API response <200ms p95
  • Sync to SendGrid within 5 minutes of change

Resources​

Open Questions​

  • Weekly Digest default? Decision: Opt-out (enabled by default) per PM 2026-01-30
  • GDPR messaging for EU users? — @legal by 2026-02-04

Definition of Done​

  • Acceptance criteria verified by QA
  • Code reviewed and approved
  • Unit tests ≥80% coverage
  • API documentation updated
  • PO acceptance received

---

## 6. Quality Checklist

### INVEST Validation Checklist

| Criterion | Check Questions | Red Flags |
|-----------|-----------------|-----------|
| **Independent** | Can ship without other stories? No blocking dependencies? | "Can only start after Story X completes" |
| **Negotiable** | Describes WHAT not HOW? Flexible implementation? | "Use Redux for state management" |
| **Valuable** | Delivers user value? Can articulate why it matters? | "Refactor database schema" (no user value) |
| **Estimable** | Team understands enough to estimate? Scope clear? | Team cannot agree on estimate range |
| **Small** | Fits in one sprint? Ideally 1-3 days? | More than 8 points; spans sprints |
| **Testable** | Can write pass/fail tests? Clear done definition? | "User has good experience" |

### Acceptance Criteria Quality Rules

**✅ Good AC Characteristics:**
- Specific and measurable ("Password 8+ characters")
- Binary pass/fail outcome
- Written from user perspective ("User sees..." not "Database updated...")
- Covers edge cases explicitly
- Quantitative where applicable ("Loads in <3 seconds")

**❌ AC Anti-Patterns to Detect:**

| Anti-Pattern | Bad Example | Good Alternative |
|--------------|-------------|------------------|
| Implementation details | "Use React hooks" | "Cart persists across sessions" |
| Vague criteria | "Intuitive UX" | "Completes in ≤3 steps" |
| Missing edge cases | Only happy path | Include error states, empty states |
| Too many criteria | 15+ scenarios | Split story if >7 scenarios |
| Non-functional mixed | "Supports 10K users" | Separate performance story |

### Definition of Ready Checklist

Before a story enters sprint planning, verify:

- [ ] **Format**: Follows "As a / I want / So that" structure
- [ ] **Value**: Business value clearly articulated
- [ ] **Persona**: Specific user type identified (not generic "user")
- [ ] **Acceptance Criteria**: Defined, specific, testable (3-7 scenarios)
- [ ] **Edge Cases**: Error and boundary scenarios included
- [ ] **INVEST**: Passes all six criteria
- [ ] **Estimated**: Story points assigned by team
- [ ] **Small**: Fits within single sprint
- [ ] **Dependencies**: All blockers identified, resolution planned
- [ ] **Resources**: Design mockups, API specs available if needed

### Top 10 Edge Case Categories

Every story should consider these edge case categories:

1. **Empty States** — No data, first-time user, zero results
2. **Boundary Conditions** — Max/min values, character limits, date ranges
3. **Permission Failures** — Unauthorized access, expired sessions, wrong tier
4. **Concurrency** — Race conditions, simultaneous edits, inventory conflicts
5. **Network Failures** — Offline, timeout, partial response, slow connection
6. **Invalid Input** — SQL injection, XSS, malformed data, special characters
7. **State Transitions** — Browser back, session expiry mid-workflow, app backgrounded
8. **Internationalization** — RTL languages, date formats, currency conversion
9. **Timeout/Expiry** — Session timeout, token refresh, long operations
10. **Bulk Operations** — Large uploads, batch deletes, pagination at scale

---

## 7. Tool Integration

### Jira Integration

**Custom Fields for Stories:**

Standard Fields:

  • Summary (required), Description, Issue Type: "Story"
  • Status, Priority, Assignee, Reporter

Custom Fields (typical IDs):

  • customfield_10016: Story Points (number)
  • customfield_10014: Epic Link (epic key)
  • customfield_10020: Sprint (sprint object)
  • customfield_XXXXX: Acceptance Criteria (textarea)

**REST API Create Issue:**
```bash
POST https://{instance}.atlassian.net/rest/api/3/issue
Content-Type: application/json

{
  "fields": {
    "project": { "key": "PROJ" },
    "issuetype": { "name": "Story" },
    "summary": "Add bulk export for admin users",
    "description": { "type": "doc", "version": 1, "content": [...] },
    "customfield_10016": 5,
    "customfield_10014": "PROJ-100",
    "priority": { "name": "High" },
    "labels": ["backend", "mvp"]
  }
}

JQL Queries:

-- Stories in current sprint
project = PROJ AND issuetype = Story AND sprint in openSprints()

-- Unestimated stories needing refinement
issuetype = Story AND "Story Points" is EMPTY AND status = "To Do"

-- Stories by epic
"Epic Link" = PROJ-100 ORDER BY priority DESC

CSV Import Format:

Summary,Description,Issue Type,Priority,Story Points,Epic Link,Labels
"User login with SSO","As a user...","Story","High",5,"PROJ-100","auth,mvp"

Linear Integration​

GraphQL Create Issue:

mutation CreateIssue($input: IssueCreateInput!) {
  issueCreate(input: $input) {
    success
    issue { id identifier title url }
  }
}

Variables:

{
  "input": {
    "teamId": "team-uuid",
    "title": "Add bulk export for admin users",
    "description": "## Story\n\n**As a** admin...",
    "priority": 2,
    "estimate": 5,
    "labelIds": ["label-uuid"],
    "projectId": "project-uuid",
    "cycleId": "cycle-uuid"
  }
}

Linear Priority Values: 0=None, 1=Urgent, 2=High, 3=Medium, 4=Low

Universal CSV Schema​

ColumnRequiredTypeJiraLinearGitHub
Summary/TitleYesStringSummaryTitleTitle
DescriptionNoStringDescriptionDescriptionBody
TypeYesEnumIssue Type—Labels
PriorityNoEnumPriorityPriority (0-4)Labels
PointsNoIntegerStory PointsEstimateLabels
EpicNoStringEpic LinkProjectMilestone
SprintNoStringSprintCycleProject
LabelsNoArrayLabelsLabelsLabels
AssigneeNoStringAssigneeAssigneeAssignees

Integration Patterns​

Design Tools (Figma → Jira):

  • Paste Figma URLs → live embeds in Jira
  • "Designs" section on issues
  • Automatic design update notifications
  • Dev Mode links layers to Jira issues

Documentation (Confluence/Notion):

  • Smart Links auto-embed Jira issues
  • PRD templates link to epics
  • Cross-reference stories in specs

Code (GitHub → Jira):

  • Branch naming: PROJ-123-feature-name
  • Smart commits: PROJ-123 #done Added validation
  • Development panel shows PRs, commits, builds

8. AI Prompt Patterns​

LLM Strengths for Story Writing​

Research from arXiv (GeneUS, ALAS papers) confirms LLMs excel at:

  • Format consistency — Reliable template adherence
  • Edge case enumeration — Systematic boundary condition identification
  • Speed — Stories generated in seconds vs. hours manually
  • Multi-perspective generation — Different personas simultaneously
  • Structured output — JSON/YAML for direct tool import

LLM Failure Modes to Prevent​

Failure ModeExamplePrevention
Too generic"As a user, I want good UX"Provide specific persona details
Missing domain contextCheckout without PCI awarenessInclude compliance requirements
Hallucinated requirementsNon-existent API endpointsCross-reference technical docs
Over-engineeringBlockchain for a contact formSpecify scope constraints
Implementation details"Use Redux for state"System prompt: "Focus on WHAT not HOW"

Effective Prompt Templates​

Template 1: Full Context Business Analyst

You are an experienced business analyst creating user stories for a [domain] application.

CONTEXT:
- Feature: [feature description]
- Persona: [name, role, goals, pain points]
- System constraints: [technical stack, compliance, performance requirements]
- Related features: [existing functionality]

GENERATE a user story with:
1. Title (verb-first, max 10 words)
2. Story statement (As a / I want / So that)
3. 4-6 acceptance criteria in Given/When/Then format covering:
   - Happy path
   - At least 2 edge cases
   - Error handling
4. In-scope / Out-of-scope lists
5. Dependencies

Focus on WHAT the user needs, not HOW to implement it.
Do not include implementation details in acceptance criteria.

Template 2: Few-Shot with Examples

Create user stories following this format:

EXAMPLE:
Feature: Password reset
Story: As a registered user, I want to reset my password so I can regain access if I forget it.
AC1: Given I'm on login, When I click "Forgot password" and enter registered email, Then I receive reset link within 5 minutes
AC2: Given I use reset link, When I set password meeting requirements, Then I can log in with new password
AC3: Given I enter invalid email, When I submit, Then I see "Email not found" error

NOW CREATE FOR:
Feature: [your feature]
Persona: [your persona]
Goal: [your goal]

Template 3: Self-Critique and Refine

Step 1: Generate initial user story for [feature]
Step 2: Self-critique for:
  - Is the value statement genuine business value (not just restating the feature)?
  - Are acceptance criteria specific and testable?
  - Are edge cases covered?
  - Is scope clearly bounded?
Step 3: Refine based on critique
Step 4: Validate against INVEST criteria
Step 5: Output final story

Human Validation Points​

Even with AI assistance, humans must validate:

CheckpointWhat to Verify
Value StatementDoes "so that" reflect real business value?
Persona AccuracyDoes actor represent actual target users?
Scope BoundariesAre in/out-of-scope appropriate for sprint?
AC TestabilityCan QA write pass/fail tests from each criterion?
DependenciesAre blocking items identified and realistic?
Domain AccuracyAre compliance/regulatory requirements captured?

Context Requirements for Quality Output​

Provide AI with:

  1. Persona details: Name, role, technical proficiency, goals, frustrations
  2. Feature scope: Problem being solved, business value, success metrics
  3. System constraints: Tech stack, performance requirements, security needs
  4. Domain knowledge: Industry terminology, regulations, existing workflows
  5. Examples: Sample stories from the same product for style consistency

9. Bibliography​

Industry Standards & Frameworks​

User Story Fundamentals​

Story Mapping & Splitting​

BDD & Gherkin​

Quality & Definition of Ready​

Tool Documentation​

AI for Requirements Engineering​

Prioritization Frameworks​

Multi-Tenant & Domain Examples​

Success Criteria Verification​

QuestionAnswer
Can describe exact output format for stories.md?✅ Section 5: Complete template with 8 sections, YAML frontmatter schema
Have complete template.md with all fields?✅ Section 5: Full template with required/optional metadata
Know the quality gates (INVEST, AC testability, DoR)?✅ Section 6: Complete checklists for all three
Identified 5-7 techniques?✅ Section 3: Story mapping, 6 splitting patterns, Three Amigos, BDD, Impact Mapping, 5 Whys
Have step-by-step skill workflow mapped?✅ Section 4: Five-phase transformation process
Collected 10+ real story examples?✅ Section 4 + AI research: CRUD, workflow, API, permission, bug fix, tech debt, SaaS, e-commerce, fintech, mobile
Listed top 10 edge cases?✅ Section 6: 10 categories with examples
Identified tool integrations and import formats?✅ Section 7: Jira REST/CSV/JSON, Linear GraphQL, GitHub templates, Azure DevOps
Have prompt patterns for AI-generated stories?✅ Section 8: 3 templates + failure mode prevention
Know common failure modes?✅ Section 8: 5 LLM failure modes with prevention strategies