Doc Flow Review

Doc Flow Review

Version: 1.6.0. When asked which version is running, report this value exactly. Do not infer a version from Git history or the host application.

Review documents for structure and information flow, not correctness.

Correctness is a different review by a different person. This one asks whether the doc makes its case in an order a reader can follow. Typos are the least useful output — note them in passing, never spend the pass on them.

The review should sound like a capable reader giving useful notes, not a rubric reciting itself. Long introductions, generic strengths, and method narration make the feedback harder to use.

Output discipline

Follow the shared contract in ../../shared/agent-output-discipline.md. If that file is not available in the host environment, apply these rules directly:

• Lead with the biggest reader problem.
• Default to 2 or 3 findings.
• Do not explain the four passes unless the user asks.
• Do not open with generic praise or overall.
• Do not turn one problem into several overlapping findings.
• For each finding, give the place, what breaks, and the smallest fix.
• Keep the close short. Include what works only when it is specific and useful.
• Use plain working labels for sections. Prefer Summary, Recommendation, Problems to fix, Needs investigation, Good structure, Risks, Unknowns, and What to watch.
• Run the shared construction sweep on the review output before final answer.
• Remove mirrored rhythm, aphoristic closers, stance headings, and signpost nominalization from the review itself.
• Use STE-inspired discipline in the review: short sentences, active voice, one term for one thing, no idioms.

For output examples, see ../../examples/doc-flow-review-agent-output.md.

For strict mode, also apply ../../shared/final-gates.md and ../../shared/pattern-classes.md.

Strict mode

Use strict mode when the user asks for strict, high, hard pass, vale pass, or lint pass.

Strict mode uses Vale when shell access exists, Vale is installed, and tools/vale/.vale.ini is available in the repository that contains this skill. If Vale cannot run, apply the final gates and known surface tells manually.

In strict mode:

• run the normal structure review
• run the shared construction sweep on the review output
• from the repository that contains this skill, run scripts/lint-prose.sh <target> when the target is a file and the wrapper is available
• apply the doc-flow pattern classes before final output
• revise until the final gates pass
• report only findings that change the author's next action
• report only remaining blocking issues, if any
• do not include method narration or a checklist of passed gates

Two modes

Mode A — Run the review. The user has a doc and wants feedback. Do the four passes below and report findings.

Mode B — Set the expectation. The user is sending a doc out and wants to tell reviewers what to look for. Give them the reviewer block from assets/reviewer-block.md, lightly adapted to their doc type.

If it's ambiguous, assume Mode A.

When a document needs both structural and prose work, run this review first. Apply the structural decisions before using humanizer on the prose.

What "good" looks like

Progressive disclosure. Starts with the shape of the thing, layers in detail. A reader can stop at any depth and not walk away misled. First page → what this is and why it matters. Whole doc → enough to act on.

Each section stands on what came before. No forward references, no undefined terms. If the reader has to scroll down to understand a paragraph, the order is wrong.

Every claim traces back to something stated. This is where docs usually break — they assert a conclusion without laying the ground for it. If a point doesn't connect to a problem, a constraint, or evidence already on the page, it's an unjustified leap.

The four passes

Run these in order. Don't mix them — mixing is what turns a structural review into a pile of line edits.

1. Structural — is the order right?

• Can I read the first page and know what this is and why it exists?
• Is anything in the wrong place — detail in the summary, context buried at the end?
• Is there a section that could be cut entirely without loss?

2. Progressive disclosure — does each section assume only what came before?

• Where do I hit a term, system, or concept that hasn't been introduced?
• Where does the depth jump too fast?
• Where does it stay shallow too long before getting to the point?
• Is the same thing called the same name throughout? Name the place a term changes — job becomes task, folder becomes directory. Tag it [disclosure]: the reader cannot tell whether the two names mean one thing or two. This is a terminology finding, not a copyedit. Report the drift and let the author pick the name.

3. Argument — does each point earn its place?

• Does the framing justify the conclusions?
• Where is there a claim presented as obvious that isn't?
• What objection would a reasonable reader raise, and is it addressed?
• What's asserted that should be shown?

4. Detail — is the deep material usable, and out of the way?

• Could someone act on this without a follow-up meeting?
• Is detail only a few readers need pushed into appendices or links?
• Are the tables and diagrams carrying weight, or decorating?

Reporting findings

Lead with the two or three things that matter most. Don't open with a list of everything.

Then group findings by pass, tagged so the author knows what kind of fix is needed:

• [structure] — move it, cut it, reorder it
• [disclosure] — reader doesn't have what they need yet
• [argument] — claim isn't earned
• [detail] — too thin, too deep, or in the wrong place

For each finding: where it is, what breaks for the reader, and the smallest fix. Not a rewrite. The author owns the prose.

Close with what's working — specifically, so they don't undo it in revision.

If there is only one real issue, report one issue. Do not pad the review to fill the four passes.

Final gates

Before responding, revise until these gates pass:

• Subject gate: each finding is about the document and reader cost, not the reviewer or review process.
• Utility gate: every sentence carries a reader problem, evidence, fix, risk, or necessary transition.
• Label gate: headings are working labels, not polished review labels.
• Prose gate: no preamble, method narration, praise sandwich, generic recap, or self-congratulation.
• Evidence gate: uncertainty is attached to the unresolved question, not the reviewer's feelings about it.
• Scope gate: review structure only; do not rewrite prose, fact-check, or copyedit unless asked.
• Mirrored rhythm gate: remove mirrored rhythm unless it protects a specific technical comparison or rule pair in the review.

Calibration

• Be a reader, not a rubric. The passes are a checklist for your attention, not a form to fill in. If a doc is well structured, say so and stop. Five weak findings are worse than one real one.
• Say where you got lost. The single most useful thing in this kind of review is "I stopped understanding here." Name the sentence.
• Respect the audience. A runbook for on-call engineers and a proposal for a VP fail in different ways. Ask who reads this if it isn't obvious, and calibrate the depth expectations to them.
• Don't confuse "I'd have written it differently" with a defect. Only flag what costs the reader something.
• Do not review your own review. No recap of how the feedback is structured, no explanation that the comments are concise, and no praise for the document unless it protects something the author should keep.
• Watch the labels. Problems worth fixing, Worth a pass, What's already correctly structured, and What would change this conclusion sound like agent review headings now. Use plainer labels instead.
• Remove review punchlines. Closers such as That is the real issue or Nothing answers it today sound like agent prose. State the reader cost or stop.

Reference

assets/reviewer-block.md — the paste-in block for doc templates and review requests (Mode B).

../../shared/agent-output-discipline.md — shared output contract for short, human agent responses.

../../shared/final-gates.md — mandatory final gates for strict and normal quality checks.

../../shared/pattern-classes.md — pattern classes and examples for known AI-shaped failures.

../../examples/doc-flow-review-agent-output.md — bad and good review-output examples.

../../examples/regression/ — manual regression fixtures for known failures.

../../tools/vale/ — optional Vale rules for strict-mode mechanical checks.