Story mode helps when a change is too broad to understand comfortably as a flat list of files. EV generates a concise narrative that groups related changes, explains why each group matters, and embeds the relevant diffs alongside that context.

It does not replace findings or the normal diff. It is another way to read the same review.

## When to use it

Story mode is useful for:

- a feature spread across several packages or architectural layers;
- a refactor whose intent is clearer as a sequence than as isolated files;
- generated or mechanical files that should remain available without dominating the walkthrough;
- a review that needs additional context around why the code changed.

For a small, focused patch, the regular **Diff** view is usually faster.

## Open a story

Start a review in Desktop:

```sh
ev review -b origin/main --desktop
```

EV generates the story for the manual review session. In the Desktop app, open **Changes** and switch from **Diff** to **Story**.

The Story view:

1. groups files into logical sections;
2. adds short context about what changed and why it matters;
3. expands the most important diffs inline;
4. keeps minor or mechanical changes available as collapsed diffs;
5. provides a table of contents for moving through a larger review.

You can switch back to **Diff** at any time. Findings, evidence, and decisions remain attached to the review rather than to one view.

## Story mode and automated reviews

`--stream` is designed for coding agents and CI. It emits findings and status as NDJSON and does not generate a story. Story mode is produced for a manual Desktop review, where the narrative can be read alongside the underlying code.

This means the choices are not simply “CLI or story.” The CLI starts both workflows:

| Goal | Command | Result |
| --- | --- | --- |
| Return findings directly to an agent | `ev review -b origin/main --stream --auto` | Streaming, agent-friendly review output |
| Understand and curate a broader change | `ev review -b origin/main --desktop` | Desktop review with Diff and Story views |

## Shape the narrative with a skill

A reviewer skill can add `story.structure` guidance when a particular kind of change should be explained in a consistent way:

```yaml
story:
  structure: Explain the request path first, then persistence and failure handling.
```

This changes the organization of the narrative; it does not change which files are in scope. See [Write a reviewer skill](/docs/guides/write-reviewer-skill/) for the complete skill anatomy.