User story layout

This page shows how a user story should look in Jira: section order, what belongs in each block, and short helptext for authors and reviewers. It matches the template bundled with the propay-jira-user-story skill; install the skill when you want Cursor to help draft or refine against the same standard.

1. Summary line

What to include: One sentence stating what changes for whom. This should align with the Jira Summary field so the backlog scan matches the description.

Helptext: Name the actor (role or persona) and the outcome, not the implementation. Avoid vague titles like “Fix bug” or “Update API” without a user-visible effect.

2. Background / context

What to include: Two to four sentences: why this work matters now, which product or area it touches, and links to Confluence, prior incidents, or decisions if they help.

Helptext: Give just enough context that someone new can understand intent. If the only “why” is a ticket number, add one line of business or risk context.

3. User story

What to include: The classic three lines:

As a <persona / role>
I want <capability>
So that <benefit / outcome>

Helptext: The want should describe observable behaviour or access, not a task list. The so that should express user or business value (or compliance), so prioritisation stays clear.

4. Acceptance criteria

What to include: Bullet points. Each item must be verifiable after implementation—ideally by QA or an automated test.

For behaviour, prefer Given / When / Then:

Given <precondition>
When <action>
Then <expected outcome>

Use plain bullets for non-behavioural checks (for example “Audit log records X”).

Helptext: If you cannot imagine a test or a clear manual check, split or rewrite the criterion. One bullet should assert one outcome where possible.

5. Dependencies

What to include:

• Jira: other keys (for example PP-1234, PP-5678).
• Systems / APIs: names, environments, or version constraints.
• Data: migrations, seed, backfill, or reporting impacts.

If there are no dependencies, write None explicitly.

Helptext: Linking keys here prevents “surprise” blockers in sprint. If dependency work is uncertain, list it under Open questions as well.

6. Out of scope

What to include: What this story does not deliver—related ideas, follow-up work, or tempting extras.

Helptext: This section reduces scope creep and makes estimation honest. If someone asks for more in review, the answer is often “new story”.

7. UX / content

What to include: Links to Figma, copy deck, screenshots, or accessibility notes. If nothing applies, state N/A.

Helptext: Designers and developers should not guess layout or copy. If UX is still TBD, say so in Open questions.

8. Analytics / events (if applicable)

What to include: Event names, properties, or funnels to validate. If the story does not change tracking, say Not required.

Helptext: Align names with your analytics dictionary so dashboards stay consistent.

9. Rollout / feature flags

What to include: Flag name, default state, rollout plan, or kill-switch notes. If not using flags, say None.

Helptext: Ops and support need to know how to enable, disable, or roll back behaviour without a new release.

10. Open questions

What to include: A numbered list of unresolved decisions, assumptions, or approvals.

Helptext: If your team gates Ready for development on clarity, unresolved items here should block that transition until answered or split out.

11. Definition of Done (team checklist)

What to include: Reference your team’s Definition of Done or paste a minimal checklist (tests, code review, docs, translations, release notes).

Helptext: Keep this aligned with the team’s actual process so “Done” means the same thing in Jira and in production.

12. Quick copy block (Jira)

Paste into the Jira description and replace placeholders. Shown in Jira wiki markup; if your project uses Markdown in descriptions, adapt headings and lists accordingly.

h2. Background
...

h2. User story
As a ...
I want ...
So that ...

h2. Acceptance criteria
* ...

h2. Dependencies
* ...

h2. Out of scope
* ...

h2. Open questions
# ...

Related

• Jira user story skill — install and update the Cursor skill from this handbook.
• Jira MCP in Cursor and Figma MCP in Cursor — optional MCP setup for live Jira or Figma context in Cursor.