---
name: dify-docs-reader-test
description: >
  Post-writing verification from the reader's perspective. Invoke after
  completing any documentation task to simulate a real user reading the
  document for the first time.
---

# Reader Experience Test

Verify a finished document by having a clean-context agent read it as the target reader, with no access to the source material, the codebase, or the writing conversation. The test only measures anything if the reader agent knows nothing you know: a subagent dispatched with the Agent tool starts with an empty context and knows only what its dispatch prompt says, so the steps below control exactly what that prompt contains.

## Procedure

1. **Get the persona.** Copy the reader persona verbatim from the rule pack used for the task: `dify-docs-guides` (Reader Personas, by document path), `dify-docs-env-vars` (Reader Persona), `dify-docs-api-reference` (Reader Persona), `dify-cli-docs` (Readers), or `ee-ops-docs` (Reader Personas; in Dify-Enterprise-Docs). If the task used no rule pack with a persona, ask the user who the target reader is before dispatching.
2. **Agree the dispatch with the owner**: how many readers, and which pages each reads. A page written or rewritten whole gets its own reader, unless several were written as one topic and sit in sequence in the navigation, in which case one reader takes them in that order. A round that changed parts of several pages can send them to one reader, who reads each whole; the reader is never told what changed, because a first-time reader does not know either. A reader who has read one page carries it into the next, so a group holds only pages a reader would reach in sequence, in the order the navigation gives them, and one persona: pages of different audiences go to different readers. One reader per page is a choice, not the default. When no reviewer is in the session, state the dispatch in the report or PR description and proceed.
3. **Dispatch the fresh subagent(s)** with the Agent tool (`subagent_type: general-purpose`). Never run the test inline in the current conversation — this conversation contains the source context the reader must not have. The dispatch prompt is the template below verbatim, with two placeholders filled:
   - `{PATHS}` — the absolute path of each finished document file, one per line. The input is the path, never pasted content: the test must run against the file on disk, not a possibly stale copy from the conversation.
   - `{PERSONA}` — the persona text from step 1, unmodified.
4. **Put nothing else in the dispatch prompt.** Each of these invalidates the test if included:
   - what the page covers, what changed, or why it was written
   - source material, code excerpts, codebase paths, or feature briefings
   - paths or links to other docs, the glossary, or the writing guides
   - your own summary of, concerns about, or questions about the draft
5. **Relay the subagent's report to the user unedited.** Then, under it, take a position on each finding: fix on this page, belongs on another page (name it), or decline, with the reason in a clause. The owner decides; nothing from the report reaches the page before that. A reader's want is evidence of a gap, not an instruction about where to fill it.
6. **On a "Needs revision" verdict**, after the owner's decisions: fix the document, then repeat from step 3 with a new subagent. Never send the revised document to the same subagent — it has context now and can no longer simulate a first-time reader. Repeat until the verdict is Clear or the user accepts the remaining gaps.

## Dispatch prompt template

```text
You are testing a documentation page by reading it as a first-time reader.

Read exactly these files, each whole, one at a time:
{PATHS}

Do not read any other file, search the repository or the web, or run any
other command. Everything you may use is in those files; if something
you need is missing, that is a finding to report, not a reason to look
elsewhere.

You are this reader:

{PERSONA}

Read each document once, top to bottom, as this person, and answer for
it:

- Can I accomplish the task described without prior knowledge?
- Are there steps that assume context not provided on this page?
- Are there terms used without explanation?
- Is the information I need actually here, or do I have to guess?
- Do the code examples make sense on their own?
- After reading, do I know what to do next?
- Where did I want advice (what to choose, what to avoid, what happens
  if I get it wrong) and get only a description?
- Which sentences told me something I could already see on screen, or
  would have assumed without being told?

Do not review style or formatting, fact-check claims against any other
source, or rewrite anything. Only report where a first-time reader
struggles or is left wanting.

Reply with exactly this structure, once per file, under the file's path:

- **Got stuck at**: [section/step where understanding broke down, or "nowhere"]
- **Didn't understand**: [terms, concepts, or references that were unclear, or "nothing"]
- **Missing context**: [assumptions the document makes that weren't established, or "none"]
- **Wanted but didn't get**: [places I needed a judgment and got a description, and sentences that told me nothing new, or "none"]
- **Verdict**: Clear / Minor gaps / Needs revision
```