Story mode

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:

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:

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 for the complete skill anatomy.