---
title: "User story layout"
description: "Human-first Jira user story structure at Propay: flow-sized stories, clear Gherkin summary, tech tasks, business rules, acceptance criteria, and test cases."
canonical_url: "https://handbook.propay.co.za/analysis/user-story-layout"
---
# User story layout

> Human-first Jira user story structure at Propay: flow-sized stories, clear Gherkin summary, tech tasks, business rules, acceptance criteria, and test cases.

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](https://handbook.propay.co.za/analysis/jira-user-story-skill) 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

<table>
<thead>
  <tr>
    <th>
      Good (flow level)
    </th>
    
    <th>
      Too small
    </th>
    
    <th>
      Too big
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Create contact
    </td>
    
    <td>
      Enter contact name
    </td>
    
    <td>
      Contact management (all CRUD + search + audit + documents)
    </td>
  </tr>
  
  <tr>
    <td>
      Update contact: personal information
    </td>
    
    <td>
      Enter surname
    </td>
    
    <td>
      Full contact module epic as one story
    </td>
  </tr>
  
  <tr>
    <td>
      Search and view contact
    </td>
    
    <td>
      Click search button
    </td>
    
    <td>
      
    </td>
  </tr>
</tbody>
</table>

## 1. Jira story title (Summary)

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

```text
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.

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

**Example:**

```text
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.

<table>
<thead>
  <tr>
    <th>
      Epic
    </th>
    
    <th>
      User stories (examples)
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Contact management
    </td>
    
    <td>
      Create contact; Search and view contact; Update contact: personal information; …
    </td>
  </tr>
</tbody>
</table>

**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.

```text
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](https://handbook.propay.co.za/analysis/jira-user-story-skill) — install and update the Cursor skill from this handbook.
- [Jira MCP in Cursor](https://handbook.propay.co.za/analysis/jira-mcp) and [Figma MCP in Cursor](https://handbook.propay.co.za/analysis/figma-mcp) — optional MCP setup for live Jira or Figma context in Cursor.


## Sitemap

See the full [sitemap](https://handbook.propay.co.za/sitemap.md) for all pages.
