Review a document for ambiguity
Finds statements in instructions, policies, requirements or agreements that readers could interpret two ways, explains each reading and its consequence, and proposes unambiguous wording.
Ambiguity is cheap to fix on the page and expensive to discover later, in a dispute, a wrong build or an inconsistent decision. Authors cannot see their own ambiguities because they know what they meant. A useful review reads as the least charitable competent reader would, finds statements with two or more plausible readings, shows the readings side by side with what each would lead someone to do, and offers wording that allows only the intended one.
Common sources of ambiguity to check:
- Lexical: a word with two meanings ("bi-weekly", "sanction", "next Friday"), or an undefined term.
- Inconsistent terms: the same thing called two names, or one name used for two things.
- Scope and attachment: what a modifier or condition applies to ("employees and contractors with a laptop"); "and" versus "or"; "and/or".
- Quantifiers and negation: "all … not", "up to", "at least", "a few", "regularly".
- Time: "within 30 days" (calendar or business, from when), "by Friday" (inclusive, which time zone), "annually".
- Reference: "it", "they", "this", "the above", "the manager" when several are in play.
- Modal strength: "should", "may", "will", "must" used interchangeably for obligations.
- Missing actor: passive voice that hides who must act ("requests will be approved").
- Vague standards: "reasonable", "promptly", "where possible", "appropriate" with no test.
- Conditions and exceptions: nested if, unless, except, and which takes precedence when two rules conflict.
Review the document below for ambiguity.Only if [DOCUMENT_TYPE] is given: Document type: .Only if [READER] is given: The reader who must act on it: .
- If the document is empty, ask for it and stop. If no reader is given, assume a competent reader who was not involved in writing it and say so in the Summary.
- Read the whole document once for purpose. Then go statement by statement looking for the sources listed above.
- For each ambiguity, record: the location (section or a few quoted words), the exact quoted text, the type, reading A and reading B (and C if needed), the practical consequence of the difference for the reader, a severity, and proposed wording.
- High: readers would act differently in ways that cost money, safety, rights, deadlines or a failed delivery.
- Medium: likely to cause questions, delays or inconsistent handling.
- Low: unlikely to mislead in practice but worth tightening.
- Proposed wording must allow only the intended reading. If you cannot tell which reading the author intended, give wording for each and ask.
- List terms that should be defined once and used consistently, with a suggested definition where the document implies one, or a question where it does not.
- Do not flag ordinary style issues, typos or wordiness unless they create ambiguity.
- Quote the document exactly; never paraphrase it in the "text" column.
- Report only genuine ambiguities with two plausible readings, not far-fetched ones. Fewer, real findings beat a long list.
- Keep proposed wording as close to the original as possible and in the document's register.
- If the document is a contract or other legal text, note once that this is a drafting clarity review, not legal advice, and that changes to binding terms should be checked by someone qualified.
Summary
Two or three sentences: how many ambiguities by severity, the most consequential one, and the assumed reader.
Ambiguities
Table: # · Location · Text · Type · Reading A · Reading B · Consequence · Severity · Proposed wording. Ordered by severity, then position.
Terms to define
Table: Term · Where used · Problem · Suggested definition or question.
Notes
Bullets: patterns across the document (for example "uses 'should' for both rules and advice") and any author questions. "None" if none.
Text: "Expenses must be submitted within 30 days with receipts over 25 EUR." Reading A: submit all expenses within 30 days; attach receipts only for items over 25 EUR. Reading B: the 30-day rule applies only to expenses over 25 EUR, which need receipts. Proposed: "Submit every expense within 30 calendar days of the purchase date. Attach a receipt for any item over 25 EUR."
1 required value still a placeholder; the assistant will ask for it.
details
- kind
- Prompt: a task you run by name to get one finished thing back
- domain
- Writing and communication
- category
- Editing
- level
- Intermediate
- made for
- Editor, Business analyst, Operations, Technical writer
- risk
- read-only
- version
- v1.0.0 · incubating
- reviewed
- 2026-10-03
- works in
- Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Antigravity, OpenCode, Windsurf, Zed, Continue, AGENTS.md, ChatGPT, claude.ai
use in
npx @hermes-hq/hodios install review-document-for-ambiguity --target claude-codenpx skills add hermes-hq/hodios-dist --skill review-document-for-ambiguity -a claude-codeclaude plugin marketplace add hermes-hq/hodios-distclaude plugin install hodios-writing-communication@hodiosThe plugin brings every entry in this domain at once.
pairs well with
All of EditingSimplify a text to plain language
Rewrites a text in plain language at a target reading level while keeping every fact, obligation, right, deadline and condition intact, and shows a meaning check against the original.
simplify-to-plain-languageCopyedit to a style guide
Copyedits a text to a named style guide such as AP, Chicago, APA or a house guide, logs every change with the rule applied, queries the author on judgement calls and keeps voice and meaning.
copyedit-to-style-guideWrite an FAQ from source documents
Builds an FAQ from scattered policies, emails and documents, phrasing entries as real readers ask them, tracing each answer to its source and listing conflicts and unanswered questions.
write-faq-from-documentsEditor
Editor who serves the reader and the author's intent, edits at the right level with structure before lines, and explains every change so the author can accept, reject or learn from it.
editorProofread a text
Corrects grammar, spelling, punctuation and consistency errors in the chosen English variety, preserving the author's voice, and lists each change with the rule behind it.
proofread-textRewrite a text for tone
Rewrites a text in a target tone or register, such as warmer, firmer or more formal, without changing its facts, asks or commitments, and shows which tone dials moved.
rewrite-for-tone