dify-docs-editor-test

# Editor Test The linters measure mechanics. This test measures the writing, and it only measures anything if the judge has not seen the research: a fresh sub-agent gets the draft, the style guide, the reference page, and the shape the page's type follows, and nothing else. ## Procedure 1. Agree the dispatch with the owner before sending anything: how many judges, and what each reads. A page written or rewritten whole gets its own judge, unless several pages were drafted as one topic and the marks need the cross-page view, in which case one judge reads the set. A round that changed parts of pages sends the touched pages to one judge, each with its changed sections named, or to several judges split by topic when the set is large. Pages of different genres go to different judges, because the reference page differs. One judge per page is a choice, not the default. 2. Dispatch the fresh sub-agent(s) (`subagent_type: general-purpose`) with the template below, filling `{DRAFT}` (absolute path), `{STANDARD}` (the style guide's path), `{EXEMPLAR}` (the reference page in the draft's genre: `en/cloud/use-dify/build/new-agent/overview.mdx` for a concept page, `en/cloud/use-dify/build/new-agent/build.mdx` for a task page or a reference), `{SHAPE}` (the pack's page-shape or conventions for this document type, as a path or a path with a section name, `path § Section`: the CLI pack's `SKILL.md § Page shape`, the API pack's `references/spec-conventions.md`, the env-var pack's `SKILL.md § Document Structure`; for a page with no pack, or whose pack has no page-shape section, the line reads "none"; add the page's genre and depth agreed at scope, or its existing genre when the round skipped scope, to this line), and `{CHANGED}` ("the whole page", or the sections and paragraphs this round changed, named as the reader would find them). When one judge reads several pages, the page block (files 3 and 4 and the changed line) and the reply repeat per page, under the page's path. The shape file keeps the judge from marking a required table or synopsis as a fault; the language inside the structure is still judged. Put nothing else in the prompt: no fact sheet, no research, no account of what changed beyond that line, no concerns of your own. 3. Relay the report unedited. A mark is evidence that a sentence falls short, not an instruction for how to fix it, so check each one before proposing anything: a mark tagged rule against the rule's own text, and a mark whose fix would add text against the style guide's test (would this reader, here, do anything differently for it?) and the page's genre (does it belong here or on the page that owns it?). Under the report, propose what to do with each mark, with the reason in a clause: fix here, move to another page (name it), or decline. The owner decides on your proposals. The verdict sets the size of the fix: "Ship with light edits" fixes the marked sentences, "Needs heavy edits" rewrites the marked units whole, from their job, and "Needs rewrite" hands the draft and the marks to whoever the Write stage gives a changed idea: a fresh drafter, or the session itself in co-writing. After either rewrite, dispatch a new judge; never send a revised draft to the same one. Marks outside the change are the page's standing debt: propose a fix in this round or a follow-up for each, and touch none of them without the owner's decision, because on a release branch a page's debt is not this round's scope. ## Dispatch prompt ```text You are the editor of a documentation set, reading a draft the way its owner would before deciding whether it can ship. Read exactly these files, in this order: 1. {STANDARD}: the whole style guide. Its opening section, "What a Good Page Does", is the standard; the sections after it are the rules a page also has to meet. 2. {EXEMPLAR}: a page the owner wrote. It calibrates register and judgment about what to leave out; the standard in file 1 is the authority. Do not copy it; measure against it. Then, for each page under review: 3. {SHAPE}: the conventions this kind of page follows (its sections, tables, synopsis blocks), given as a file or as one named section of a file; read only that section. A structure the conventions require is not a fault; judge the sentences inside it. If the line also names the page's genre or depth, judge the page against them too; if it names no file, read nothing for it. 4. {DRAFT}: the page under review. This round changed: {CHANGED}. Read the whole page regardless: a sentence is judged in the context the page gives it, and a change is judged by whether it fits the page it landed in. Read nothing else and run no other command. Mark every sentence in the draft that falls short of the bar, quoting it, with one tag each: - transcribed: a fact stated with no reader who would ask for it here - reason: a why-clause on an instruction the reader would have followed anyway - interface: describes what the reader can see on screen at that moment - dense: two separable ideas in one sentence, or a paragraph that runs past the point where the reader's question changed - structure: a section or paragraph out of the reader's order, off its heading, repeating another part of the page, or one this page's reader wouldn't need; quote its heading or first sentence - vocabulary: a word from the code, the spec, or the team, not the product - missing: a place the reader needed a judgment (what to choose, what to avoid, what happens if they get it wrong) and got a description - rule: breaks a rule in a later section of the style guide; name the section Then give one verdict on this round's work: Ship with light edits / Needs heavy edits / Needs rewrite, with one sentence on what decided it. Marks outside the change do not move the verdict; list them separately. Do not check facts, formatting, links, or terminology. Do not rewrite. Judge only whether this is writing the owner would put their name to. Reply with exactly this, once per page, under the page's path: - **Marked, in this change**: [quoted sentence — tag — five words on why; for rule, the section], one per line, or "none" - **Marked, elsewhere on the page**: same form, or "none" - **Best passage**: [the section that meets the bar, in a phrase] - **Verdict**: [one of the three, and the deciding sentence] ```