# User stories and scenarios

Expand settled requirements into a form the development team can pick up as-is.

![PM on Rails user stories. Development units, summaries and the path into acceptance scenarios. Before: you judged done right before delivery. After: you agree what done looks like first.](https://pmonrails.com/docs-img/stories.png)

![User-story video. Open a story and read the Given, When and Then of its acceptance scenarios. You pass more than a task title: what done looks like.](https://pmonrails.com/docs-video/stories.webm)

## Creating stories

- **Generate from a requirement card** — Generate 1 to 5 user stories and their scenarios from a single requirement in one go. Large requirements get split into sizes that are easy to implement.
- **Generate from text** — Meeting notes, design memos, content pasted from other tools: you can raise several stories from free-form text as well (no requirement card needed).
- **Draft scenarios for you** — As long as the title or the outline is decided, AI proposes a first cut of the scenarios.
- **Regenerate everything** — When the generated result heads in a different direction from what you wanted, you can delete every story under that requirement and build them again (this cannot be undone, so you get a confirmation).

## Scenarios (the bar for done)

Open a story and you see its overview, business value and preconditions, followed by scenarios written as Given / When / Then in a **readable heading hierarchy**. The list does not expand scenarios deeply; read them on the detail screen. Scenario actions are text links.

![PM on Rails acceptance scenario. Given / When / Then writes the check for done. Before: 'done / not what I meant' arrived just before delivery. After: the test has a written basis first.](https://pmonrails.com/docs-img/scenario.png)

- **Scenarios** — Write the bar for completion in the form 'in this situation, when you do this, this happens' (Given / When / Then). You can choose the type: happy path, error case or boundary value.
- **How status flows** — A scenario becomes **active** the moment it is registered. While the content is still under discussion you can move it down to draft, in review or approved and progress it in stages (a review can send it back, and a scenario can be replaced by a newer version or deprecated once it goes stale).
- **Editing an agreed scenario** — When you edit a scenario that is already **active (agreed)**, the new version stays **active** (so CI Scenario IDs and the test source of truth stay aligned). Moving back to draft is an explicit status change. You can leave an optional **reason for the change** (stored as a memo on the saved version). The same optional reason applies when updating tasks.
- **Comments** — On each story and scenario, comments appear as a **conversation**: author, time, type and body stacked vertically. The list view does not embed a comment area; open the detail screen.

## AI review (gaps in happy paths, error cases and boundary values)

Before work starts, AI surfaces **what is missing** from your stories and scenarios. You can look at them one at a time, or look at the stories currently listed all together.

![PM on Rails AI review. Gaps, ambiguity and contradictions in a list. Before: review quality depended on who looked. After: what to ask becomes material for questions.](https://pmonrails.com/docs-img/ai-review.png)

- **Single review** — Use 'AI review (missed happy-path / error cases)' on a story row to check just that story.
- **Bulk review** — Use 'Other actions → Bulk AI review' to check every story in the current filter at once. When there are many stories the work runs as a background job, so it keeps going even if you close the screen.
- **Revisit past reviews** — Use 'Other actions → Past AI reviews' to open saved bulk review results. You can read the findings from that run without calling the LLM again.
- **Keep questions as open questions** — Rather than only copying the 'Questions for stakeholders' that AI produces, you can 'keep as an open question' and collect them under [open questions](https://pmonrails.com/en/docs/clarifications.md).
- **Draft the fixes** — From the findings of a bulk review, pick which findings to reflect and where to reflect them (a new scenario / an existing scenario / the preconditions on the story itself), and have AI draft them. Generating alone saves nothing: you check each row and save it.

## Upstream changes and update proposals

When a requirement card or a requirement changes, the story screen shows them together as 'unreviewed upstream changes'.

- **Unreviewed upstream changes** — See a list of the requirement card and requirement changes you have not looked at yet. Marking them reviewed only clears your own view; everyone else keeps their unreviewed state.
- **Show only what changed** — Filter down to the stories that have upstream changes.
- **Apply update proposals in bulk** — The downstream update proposals AI builds from upstream changes are applied only after a person approves them. You can also apply several proposals at once.

## List filters and share links

- **Advanced filters** — From "Filter" at the top of the list you can combine state, development cycle, priority (MoSCoW), links to requirement cards / requirements, whether a GitHub issue exists, and completion of child tasks with **AND** logic. When filters are active, the button shows how many are applied.
- **Copy link** — Each story row and each scenario has a "Link" control to copy a URL that opens the same screen (you can copy comment links from the detail view too). Use it when you want to say "look at this story" in Slack or email.

## Exporting to GitHub and Markdown

Stories do not stay locked inside PM on Rails.

- **Markdown export** — 'Other actions → MD export' takes the story overview and scenarios out as Markdown.
- **Bulk GitHub export** — When you have stories that are not connected to GitHub yet, 'Other actions → All to GitHub' turns them into issues in one go.
- **Bulk GitHub push** — For stories already connected, 'Other actions → Push all' reflects the latest PM on Rails content into the issues all at once.
- **Pull from an issue** — Gherkin that was edited on the issue side can be pulled back into PM on Rails from the actions on an individual story.

## Breaking work down into units of development

Once a story is settled, hang **tasks** under it and get development moving. For assignees, priority, estimates and running the board see [task management](https://pmonrails.com/en/docs/tasks.md); for how bugs and spec changes are handled see [bugs and change management](https://pmonrails.com/en/docs/bugs-changes.md).

## Next steps

- [Task management](https://pmonrails.com/en/docs/tasks.md) / [Testing](https://pmonrails.com/en/docs/test-results.md) / [Claude Web, Claude Code and MCP integration](https://pmonrails.com/en/docs/mcp.md)

---

https://pmonrails.com/en/docs/stories