Reviewing User Guide

reviewing-user-guide — SKILL.md

> Variant: standard · When to use: judging a finished end-user guide as an acceptance gate — checking a real user can accomplish every supported goal from it against a single-sourced 12-condition bar, then emitting VERDICT: approve|revise with actionable findings.

Overview

This skill is the review half of a producing/judging end-user-guide pair. Loaded by a reviewer who holds a finished end-user guide — the consumer-facing help the person using a product (typically non-technical) reads to accomplish their goals (a getting-started tutorial, task-oriented how-to guides, conceptual explanation, an end-user feature/configuration reference, troubleshooting/FAQ, and a glossary) — it judges that guide against one question: can a real user of the product accomplish every supported goal from this guide alone, without asking the author, with steps that match how the product actually behaves and language a non-technical reader can follow? It applies a fixed 12-condition usability + accuracy checklist — the same bar a user-guide author produces to, single-sourced and numbered identically so the produce-bar and the review-bar do not drift — then emits a single machine-parseable verdict plus findings the author can act on in one revision pass. It judges the textual markdown artifact (prose, fenced snippets, screens described in words with wireframe links), not a rendered help site; the method and bar are medium-independent. It is an acceptance gate — it does not author, fix, or rewrite the guide; it judges and returns findings, and the producer revises.

When to activate

• A finished end-user guide needs an accept/revise decision before it ships to its users.
• You are the independent reviewer / gate for an end-user guide a producer just authored.
• Re-judging a revised end-user guide after a prior revise verdict.
• Reviewing an amend — a versioned delta on a published guide after an upstream change (judged delta-scoped, cond-9).

Do NOT activate when:

• Authoring or repairing an end-user guide -> use a user-guide-authoring skill (it produces to the same bar this skill asserts). This skill never writes the guide.
• Reviewing a developer adoption/integration guide — the onboarding narrative for an SDK, library, CLI, framework, or API platform that a developer reads to integrate a tool -> use a developer-guide-review skill. That gate judges developer adoption; this gate judges the end-user product guide.
• Reviewing an API reference — the developer-facing HTTP/SDK endpoint catalog (endpoints, fields, errors, contract-consistency) -> use an api-reference-review skill. That gate judges contract-consistency, not end-user usability; the end-user reference here is the product surface (features, settings, CLI commands), NOT the HTTP API.
• Reviewing an engineering design document — an architecture spec, design doc, ADR, or RFC -> use a design-review skill that verifies design claims against the codebase. Distinct gate, distinct bar.
• Checking template/section conformance -> that is a template concern. This skill judges quality against the bar, not whether every heading is present.

Workflow

Step 1: Read the whole guide with fresh, independent eyes, and gather the upstreams

Read the guide end to end as if you were the target (typically non-technical) user encountering it for the first time, without the author's framing. Your stance is a gatekeeper for the user: a finding carries weight only when it shows a real user cannot accomplish a supported goal from the guide as written, or when a step would lead the user wrong because it does not match the product.

Then identify the handed-in upstreams the guide was produced from — its depends_on set (typically a feature-spec, user-flows, and/or wireframes; sometimes only a PRD; sometimes a design-system for UI terms). Enumerate the user goals from the user-flows when user-flows is present (each flow is a user goal/job); when user-flows is absent, take the goals from the feature-spec / PRD. Judge coverage against whatever upstream was actually handed in — never assume user-flows is always present. If an expected upstream is absent, note it as an assumption you are reviewing under; do not invent a goal the upstreams do not support, and do not fault the guide for a document the project never produced.

Amend mode (detected by input signal): if you are handed an existing guide + a change request + the changed upstreams, judge the delta under cond-9 — not a full re-review.

Step 2: Run the 12-condition usability + accuracy checklist — judge each condition

For each condition below, decide pass or gap. A condition fails only on a real, named deficiency — "I'd have worded this differently" is not a gap. For each gap, capture the exact location and what is missing (Step 4 turns it into an actionable finding). The conditions are the single-sourced bar (identical to the author's Step-10 self-check, numbered the same); do not add private ones.

1. Goal coverage — one how-to per goal, no orphans. Every user goal enumerated from the handed-in upstreams (Step 1) has exactly one task-oriented how-to, and every how-to traces back to a goal. Gap when a goal has no how-to (a coverage hole), or a how-to exists for no upstream goal (an orphan that may signal an invented feature).
2. Four Diataxis modes present AND correctly typed. Tutorial, how-to, explanation, and reference are all present and not conflated — the tutorial is a single guaranteed happy path (no choices/failure branches, every step yields a visible result); a how-to is imperative numbered steps (NOT a concept dump); explanation has no steps; reference is neutral + complete. Gap when a mode is missing, or written as another mode — a how-to padded into a concept dump, an explanation that smuggles in steps, a tutorial branching into alternatives. (Mixing modes is the #1 cause of doc confusion.)
3. End-user feature/config reference complete. Every user-facing feature, setting, and CLI command/shortcut the product exposes is documented; the reference mirrors the product; it describes, does not instruct. Gap when a user-facing feature/setting/command is missing or stale. (It is the end-user product surface, NOT the HTTP API — do not fault it for omitting endpoints.)
4. Steps accurate to the actual product behavior — incl. UI terminology. Every procedural step matches a behavior in the handed-in upstreams (spot-checked against the feature-spec / user-flows); no invented step, setting, screen, or menu; and each control is named by its exact product/design-system label (a step that names a control the product doesn't have, or by the wrong label, is an accuracy gap). Gap on a step that contradicts the upstream behavior, a fabricated feature/screen with no upstream basis, or a label that doesn't match the product. Fabrication is a hard fail.
5. Procedure mechanics sound. How-tos and the tutorial use numbered steps, one action per step, second person, present tense, imperative voice, task-based headings (bare infinitive, e.g. "Add an account"), naming controls by their exact labels. Gap when procedures are unnumbered prose blobs, bundle several actions per step, or use noun-phrase/feature-named headings instead of task headings.
6. Troubleshooting covers the known error states. Every error/recovery path from the handed-in upstreams (the user-flows' error/recovery paths and the feature-spec's error handling) appears as a symptom -> cause -> fix entry, organized by user-visible symptom; recurring questions are in the FAQ; a "get more help" pointer exists. Gap when a known error state is left undocumented, or entries are organized by internal cause rather than user-visible symptom.
7. Usable by the target audience. A real user (typically non-technical) could accomplish every supported goal from the guide alone, without asking the author; prerequisites are stated; screens are described in words and wireframe-linked rather than assumed visible. Gap when an ambiguity, missing prerequisite, or undefined step would block the user mid-task. (Language comprehensibility — jargon/readability — is cond-10; do not double-judge it here. This condition is the accomplish-the-goal / prerequisite / screen-description outcome.)
8. Assumptions/gaps surfaced. Where an upstream was absent or thin, the assumptions the guide made are stated (challengeable), not silently invented. Gap when a missing upstream answer was fabricated to look complete instead of flagged as an assumption.
9. Amend is a scoped, swept, versioned delta (n/a on a greenfield first build). On an iteration: the delta meets the bar on what it touched; the upstream staleness sweep is complete — no changed/removed/renamed capability is still referenced by a stale step / reference entry / screen link / troubleshooting entry / glossary term (a structural "find every reference" check); internal coherence holds (the tutorial still runs, the modes stay typed, the reference still mirrors the product); the revision-history is updated; superseded/removed items are marked. Gap on an incomplete sweep (a stale reference survives), broken coherence, missing change-history, or an unmarked removal. Detected by the input signal (an existing guide + change request + changed upstreams).
10. Plain language / readability. A non-technical reader can follow the guide: purpose-first; reasonable sentence length; every product-specific term and acronym defined on first use (and collected in the glossary); no unexplained acronym; an audience-fit reading level. Judged by outcome (a real user can follow it), NOT a readability score. Gap when unexplained jargon or a bare acronym would block the non-technical reader mid-step. (Overlap guard: a jargon/readability defect is cond-10; an unfollowable-flow / missing-prerequisite defect is cond-7 — do not double-penalize the same defect under both.)
11. Accessibility (proportional). In the textual artifact: link text is meaningful (no bare "click here"); headings nest correctly (no skipped levels); no step relies on color alone ("click the green button") or location alone ("the button on the right") — controls are named by label; described screens carry alt-text intent. Gap on a bare-link / color-only / location-only instruction that would block a reader who can't perceive the cue. (Proportional — n/a where there are no links/images/color cues. Pixel contrast and focus appearance are the rendered-site / design-system's concern, NOT judged here.)
12. Findability / start-here. A first-time reader can locate the start-here (the tutorial) and their goal's section across the doc set without already knowing the product (a §1 signpost / navigable structure). Gap when there is no start-here orientation and a reader can't tell which document answers their question. (Overlap guard: worded distinct from cond-1 "organized by goal — coverage" and cond-2 "modes typed"; trivially holds for a one-page guide; do NOT revise under cond-12 a defect already caught by cond-1/cond-2.)

Proportionality. "Usable to accomplish every goal" scales with the product. A thin product's guide legitimately collapses sections it does not need and carries a handful of how-tos — that is correct sizing, not a gap. A thin guide also legitimately has nothing to amend (cond-9 n/a on first build), no jargon to define (cond-10 trivially passes), no images/color cues (cond-11 n/a), and is trivially findable (cond-12). Judge coverage of the goals the upstreams actually carry + accuracy + a non-technical reader can follow it, not section count or word count. A small, complete guide that satisfies every applicable condition passes. Do not manufacture a gap from brevity. (The hard floor in condition 1 still holds at any size: a goal the upstreams carry must have a how-to.)

Step 3: Decide the verdict

• approve — every applicable condition passes. A real (non-technical) user can accomplish every supported goal from the guide as written; the modes are correctly typed; the steps match the product and name controls correctly; the language is followable. Approve even if you can imagine wording improvements; the bar is usability + accuracy, not perfection — and not maximalism.
• revise — one or more conditions have a real, named gap that blocks a user (a goal with no how-to, a conflated/mistyped Diataxis mode, an incomplete reference, a fabricated/inaccurate/mislabeled step, an undocumented known error state, an incomplete amend staleness-sweep, unexplained jargon, a color-/location-only instruction, no start-here a reader can navigate from, etc.).

Do not revise to signal effort or to request nice-to-haves. A condition is either met or it isn't.

Step 4: Emit the verdict + actionable findings

Emit the verdict as a single line — the literal text VERDICT: approve or VERDICT: revise, on its own line, with no surrounding code fences, quotes, or extra words (the fences here are illustration only):

VERDICT: approve

Then, on the following lines, list findings. On revise, every finding is actionable — the failed condition (by number), the exact location, and how to fix it — so the author can resolve it in one pass. On approve, findings are optional non-blocking notes; do not let them imply a revision is required.

A good finding names the gap and the fix:

> revise — Goal coverage (cond. 1): the user-flows carry a "Reset password" goal but the guide has no how-to for it. Fix: add a task-oriented "Reset your password" how-to (numbered steps from the flow's happy path).

> revise — Plain language (cond. 10), "Configure SSO" how-to: step 2 says "provision the IdP via SAML metadata" with no definition of IdP/SAML for the non-technical reader. Fix: define IdP and SAML on first use (and in the glossary), or restate the step in plain language.

A bad finding is vague and unactionable:

> The guide could be clearer. (Which goal? Which mode? Which step? What fixes it?)

Rules

Hard rules (never violate):

• Emit exactly one verdict line, VERDICT: approve or VERDICT: revise — that literal token, on its own line, nothing else on it. Downstream tooling parses it.
• Judge, never author. Return findings; do not rewrite, fix, or fill in the guide. The producer revises.
• Single-sourced bar. Judge against the twelve conditions in Step 2 — the same bar the author produces to, numbered identically. Do not invent extra conditions or apply a stricter private standard.
• No false-revise. A guide that meets every applicable condition is approved, even a thin one for a small product. Proportional sizing that still covers the goals is not a defect. Revise only on a real, named gap.
• No false-approve. Never approve over a genuine gap to be agreeable. A blocking gap is a revise.
• Honor the two overlap guards. Do not double-penalize: a jargon/readability defect is cond-10 (not also cond-7); a navigation/findability defect is cond-12 (not also cond-1/cond-2). A single defect yields a single finding under the condition that owns it.
• Enumerate goals from whatever upstream was handed in. Take goals from the user-flows when present, else the feature-spec/PRD — never assume user-flows is always there. A not-produced upstream is never a revise trigger; flag its absence as an assumption. But a guide that ignored a produced upstream (a goal in the handed-in user-flows with no how-to, a step that contradicts the handed-in feature-spec) is a fair finding.
• The reference is the end-user product surface, not the HTTP API. Judge completeness over features/settings/CLI commands the product exposes (c

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: bm629
• Source: bm629/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.