User story layout

This page shows how a user story should look in Jira. Write for people first—BA, QA, developers, and support should understand the story without decoding AI-style or overly formal wording. It matches the template bundled with the propay-jira-user-story skill.

Principles

• Human-first: Use plain language. Say what the user can do, not how the system is “implemented” or “leveraged”.
• Flow-sized: One story = one meaningful use case or user flow (for example Create contact, Update contact: personal information, Search and view contact).
• Not too small: Do not split into one story per field (for example “US1: enter name”, “US2: enter surname”) unless each field has its own business process, permissions, or release path.
• Not too big: Split when a single flow has too many screens, permissions, integrations, or test cases to deliver and verify in one sprint.

Story sizing examples

1. Jira story title (Summary)

What to include: Standard user story line in the Jira Summary field:

As a <role>, I want <capability>, so that <outcome>

Example: As a user, I want to create a contact in the Petra system, so that I can view and maintain the contact profile.

Helptext: Name the actor and the outcome, not the implementation. The title should match what someone sees in the backlog.

2. Jira description (Gherkin summary)

What to include: A short Given / When / Then block at the top of the description. This is the “at a glance” intent—keep it readable, not a full specification.

Given <precondition>
  <detail if needed>
When <trigger or user goal>
Then the user can
  <outcome 1>
  <outcome 2>
  <outcome 3>

Example:

Given a user
  Has permission to view and create a contact
When the user wants to create a new contact
Then the user can
  Search existing contacts to confirm the contact profile does not exist
  Create a new contact
  See confirmation that the contact profile is created

Helptext: If the Then list grows past roughly five items, consider splitting into another flow-sized story.

3. Background

What to include: One short paragraph: why this work matters, who cares, and any link to Confluence or a decision if useful.

Helptext: Enough context for someone new. Avoid repeating the Gherkin block word for word.

4. Tech tasks

What to include: Implementation notes for developers—screens, APIs, permissions, data, audit—grouped by what needs to be built. Use a numbered list; nest details where it helps.

Helptext: This is how we build it; the Gherkin summary is what the user gets. Keep tasks concrete (for example “Add Create new contact button on contact grid”) rather than vague (“Implement contact feature”).

5. Business rules

What to include: Rules that must always hold: permissions, tenancy, validation, audit, dynamic forms, messaging, and similar constraints.

Helptext: Number each rule. If a rule applies only to one field, it still belongs here when it is a policy, not a separate story.

6. Suggested fields (optional)

What to include: Field groups and field names when the story involves a form or wizard. Omit this section for non-UI stories.

Helptext: Helps BA and QA align on scope; dynamic form tenants may override labels—say so in business rules.

7. Suggested flow (optional)

What to include: Step-by-step user journey for the flow (open screen → act → save/cancel → system response).

Helptext: Use when the happy path is not obvious from tech tasks alone.

8. Acceptance criteria

What to include: Short, testable outcomes—what “done” means for this flow. Prefer ability-style bullets QA can check.

Example:

• Ability for a user with correct permissions to search for a contact
• Ability for a user with correct permissions to create a new contact
• Proper inline validations when field validation fails
• Proper toast confirmation or failure messages

Helptext: Each line should be verifiable manually or with a test. Do not duplicate the entire test case section here—keep ACs as the checklist; use Test cases for steps and pass/fail.

9. Test cases

What to include: Named scenarios (TC1, TC2, …) with steps and explicit Pass / Fail results.

Helptext: QA and developers use this for execution. One test case per major path (happy path, permission denied, validation failure) is enough unless risk demands more.

10. Dependencies (when needed)

What to include: Jira keys, APIs, data migrations, or feature flags. Write None if there are no dependencies.

Helptext: Prevents surprise blockers in sprint planning.

11. Out of scope (when needed)

What to include: What this story deliberately does not include—often follow-up stories under the same epic.

Helptext: Stops scope creep during implementation and review.

Epic layout

Use an Epic for a larger business outcome that spans several flows (for example Contact management). The epic should not repeat full test cases or field lists—those live on flow-sized stories.

Epic description should include:

• Goal: One or two sentences on the business outcome.
• Scope: Which flows are in vs out of the epic.
• Links: Child story keys or a Jira filter once stories exist.

Helptext: If you cannot name at least two flow-sized stories under the epic, the work might be a single story instead of an epic.

Optional sections (use when relevant)

• UX / content: Figma or copy links; N/A if not applicable.
• Analytics / events: Event names or Not required.
• Rollout / feature flags: Flag name and plan, or None.
• Open questions: Numbered list; block Ready for development until resolved if that is team policy.

AI-assisted drafting

Cursor and other agents may use structured JSON for tooling—that format is optional and documented in the skill’s ai-friendly-extended reference. The Jira description your team reads should always follow the human-first sections above.

Quick copy block (Jira)

Paste into the Jira description and replace placeholders. Adapt headings if your project uses Markdown instead of wiki markup.

h2. Description (Gherkin)
Given ...
When ...
Then the user can
* ...

h2. Background
...

h2. Tech tasks
# ...

h2. Business rules
# ...

h2. Suggested fields
...

h2. Suggested flow
# ...

h2. Acceptance criteria
* ...

h2. Test cases
h3. TC1: ...
# steps
*Pass:* ...
*Fail:* ...

h2. Dependencies
None

h2. Out of scope
* ...

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.