User Story Elaboration — Detailed Markdown
Use this when a one-liner needs to become a fully elaborated story that's ready for engineering refinement, QA, and Jira. Output is a structured markdown document — every section filled, no skipped fields, ready to paste into a Jira description or a Confluence page.
This template differs from the JSON-output user-story generators (user-story-api, user-story-ui, user-story-gherkin) — those produce machine-parseable specs for tooling. This one produces a human-readable elaboration with tables, narrative context, and a definition-of-done checklist.
When to use
- A backlog ticket has a title but no body, and refinement is in 3 days
- You want every team member to elaborate stories the same way
- The story will be reviewed by humans (PO, tech lead, QA) before development starts
- The output goes into Jira / Confluence as the story body
Prompt
You are an expert Agile Business Analyst. Elaborate the following one-line
story into a fully detailed Agile user story using the exact markdown
template below. Fill every section. Never leave a section blank — write
"Not applicable" or "⚠️ UNCLEAR: <reason>" if you genuinely don't know.
## Inputs
**One-liner:** {{one_liner}}
**Story ID:** {{story_id}}
**Epic context:** {{epic_context}}
**Project context:** {{project_context}}
## Output requirements
Return ONLY the markdown document below — no surrounding commentary, no
"here's your story:" preamble, no closing notes.
---
## 📋 Story Header
| Field | Value |
|---|---|
| **Story ID** | <use the input or leave as TBD> |
| **Epic** | <epic name + ID if known, else "TBD"> |
| **Sprint** | TBD |
| **Priority** | <High / Medium / Low — infer from one-liner urgency> |
| **Story Points** | TBD — for dev to estimate |
| **Status** | Backlog |
---
## 🗣️ User Story Statement
> **As a** <specific persona — be precise, not "user">
> **I want** <specific capability or action>
> **So that** <business benefit or user outcome>
---
## 📖 Background & Context
<2-4 sentences. Explain WHY this story exists. Reference the current state
and target state when relevant. Don't repeat the AS/I-WANT/SO-THAT —
this is the surrounding context.>
---
## ✅ Acceptance Criteria
> Format: Given <precondition> / When <action> / Then <expected outcome>
> Minimum 6 criteria. Each must be independently testable.
> Always include at least one error / edge-case AC.
**AC-1: <Short title>**
- **Given** ...
- **When** ...
- **Then** ...
**AC-2: <Short title>**
- **Given** ...
- **When** ...
- **Then** ...
**AC-3: <Short title>**
- **Given** ...
- **When** ...
- **Then** ...
**AC-4: <Short title>**
- **Given** ...
- **When** ...
- **Then** ...
**AC-5: <Short title>**
- **Given** ...
- **When** ...
- **Then** ...
**AC-6: <Short title — error / edge case>**
- **Given** ...
- **When** ...
- **Then** ...
---
## 🚫 Out of Scope
<List at least 3 things this story explicitly does NOT cover. Link to the
story that covers it if known. This is the section that prevents scope
creep.>
- ❌ <Item 1> → Covered in <story ID if known>
- ❌ <Item 2>
- ❌ <Item 3>
---
## 🔧 Technical Notes
| Area | Detail |
|---|---|
| **APIs / Endpoints** | <Specific endpoints, e.g. POST /carts/:id/line-items> |
| **Data entities** | <Domain entities involved> |
| **UI components** | <Component names or "Not applicable"> |
| **Integrations** | <Third-party services if any> |
| **Existing-system impact** | <Does this affect legacy pages / services / batches?> |
| **Feature flags** | <Flag name if gated> |
---
## 🔗 Dependencies
| Dependency | Story / Team | Status |
|---|---|---|
| <e.g. Auth tokens issued by IDP> | <Story ID or team name> | <Done / In Progress / Blocked> |
---
## ☑️ Definition of Done
- [ ] Code implemented and peer-reviewed
- [ ] Unit tests written and passing
- [ ] Integration tests passing in the appropriate sandbox
- [ ] Acceptance criteria verified by QA
- [ ] No regressions on adjacent flows
- [ ] Deployed to <staging environment name>
- [ ] Product Owner sign-off
- [ ] Jira story updated to "Dev Complete"
---
## Style guide
- Personas: be specific. "B2B procurement admin with multi-SKU PO authority"
beats "user".
- ACs: each verifies one behavior. Don't AND multiple checks.
- Out of Scope: name what's NOT in the story to head off scope arguments.
- Technical Notes: link real endpoints / components / flags. If you don't
know, write "TBD — see <person/team>", never guess.
- Definition of Done: keep the standard items; add story-specific ones
(e.g. "Accessibility audit passed", "Data migration script tested").Example output (excerpt)
## 📋 Story Header
| Field | Value |
|---|---|
| **Story ID** | FIN-8751 |
| **Epic** | EPIC-204 — Cart & Checkout Migration |
| **Sprint** | TBD |
| **Priority** | High |
| **Story Points** | TBD |
| **Status** | Backlog |
## 🗣️ User Story Statement
> **As a** B2C individual subscriber on the Pluralsight web app
> **I want** to add a Pluralsight subscription to my cart from any course detail page
> **So that** I can purchase it without navigating away and losing my browsing context.
## 📖 Background & Context
Today, clicking "Subscribe" from a course detail page redirects to a
legacy AEM checkout page — losing the user's session context and
producing a measurable drop in conversion. As part of the commercetools
migration, we're replacing the cart with a CT-backed React widget that
appears inline on the course page, so the user stays where they are.
## ✅ Acceptance Criteria
**AC-1: Add subscription to cart from a course page**
- **Given** I am viewing a course detail page and not signed in
- **When** I click "Add to cart" on the subscription tile
- **Then** the cart icon updates to show "1 item" and a slide-in confirms
"Added — Pluralsight Personal · $29/mo"
[... AC-2 through AC-6 ...]Tips
- Pair this with the Test Case Comprehensive template — paste the elaborated story in and get the matching multi-category test cases.
- For Jira upload, run the Jira Push (Bulk) skill against
output/[STORY_ID]_elaborated.md. - If the story crosses backend + frontend, generate the elaboration here, then run the API and UI generators on the same one-liner to get the corresponding tickets.
- For regulated environments, use the Enterprise user-story variant instead — it adds compliance, security, and audit sections.