| name | doc-review |
| description | Dual-dimension document quality gate — presentation rubric + hallucination grounding check |
| version | 0.1.0 |
| level | 2 |
| triggers | ["/doc-review","review this doc","check for hallucinations","hallucination check","doc quality check"] |
| context_files | ["context/user.md"] |
| steps | [{"name":"Scope","description":"Identify the document type and its stated sources. If no sources are declared, ask the user before proceeding."},{"name":"Presentation Pass","description":"Evaluate structure, clarity, and completeness against the rubric."},{"name":"Hallucination Pass","description":"For each factual claim, verify it against the stated source material. Flag ungrounded claims."},{"name":"Verdict","description":"PASS / REVISE / BLOCK with specific, line-referenced feedback."}] |
Doc Review Skill
Two-pass quality gate for generated documents. Run before delivering any report, PRD, ADR,
email, research summary, wiki page, or other prose output where accuracy matters.
What Claude Gets Wrong Without This Skill
Without explicit review, generated documents can pass a surface quality check while containing
factual claims that were hallucinated — plausible-sounding assertions with no grounding in the
source material. Claude Code averages 10+ hallucinations per generated research paper.
A one-pass review catches presentation issues but misses grounding failures.
The two-pass structure separates these concerns: Presentation checks quality; Hallucination
checks truth. Both must pass independently.
Overview-Anchor Pattern
For long documents (PRDs, ADRs, research summaries), use the overview-anchor pattern before
writing the full document:
- Generate a brief overview (title, 3-5 bullet points, sources list) first
- Present the overview to the user for confirmation
- Generate the full document from the confirmed overview
This reduces hallucination risk: the overview forces explicit source declaration upfront, and
each section of the full document is anchored to a confirmed claim.
Pass 1 -- Presentation
Evaluate the document against this rubric:
| Dimension | Score (1-5) | Criteria |
|---|
| Structure | | Clear sections, logical flow, no orphaned content |
| Clarity | | No ambiguous claims, jargon explained, terms consistent |
| Completeness | | All stated goals addressed, no missing sections |
| Audience fit | | Appropriate for the stated reader (technical vs. non-technical) |
Score 1-2 on any dimension = REVISE. Score 1 on any = BLOCK.
Common presentation failures:
- Section headings that do not match their content
- Claims in the introduction not addressed in the body
- Inconsistent terminology for the same concept
- Conclusions that go beyond what the body supports
Pass 2 -- Hallucination Check
For each factual claim in the document:
- Identify the source it should be grounded in (stated explicitly or inferable from context)
- Verify the claim against that source
- Flag any claim that cannot be verified
Claim categories:
| Category | Grounding requirement |
|---|
| Statistics / numbers | Must match source verbatim or cite approximate |
| Named entities (people, orgs, tools) | Must be verifiable from source or prior session context |
| Causal claims ("X causes Y") | Must be explicitly stated in source, not inferred |
| Recommendations | Must follow logically from verified claims |
| Quotes | Must be exact; partial quotes must not change meaning |
Ungroundable claims (not necessarily wrong, but unverifiable):
- Claims about future behavior
- Claims about user intent not stated in source
- Generalizations from single examples
Flag ungroundable claims separately from hallucinations. They may be valid but must be
surfaced for the user to validate.
Verdict Format
PASS: Document meets presentation standards and all factual claims are grounded.
State any minor observations that do not require changes.
REVISE:
Issue: [description]
Location: [section or line reference]
Dimension: [presentation / hallucination / ungrounded]
Fix: [specific recommendation]
Blocking: No
BLOCK:
Issue: [description]
Location: [section or line reference]
Dimension: [presentation / hallucination / ungrounded]
Impact: [what the reader would believe incorrectly]
Fix: [specific recommendation]
Blocking: YES
Hallucination findings that would mislead the reader are always BLOCK, not REVISE.
Document Types and Source Expectations
| Document type | Expected sources |
|---|
| Research summary | Source papers/URLs declared upfront |
| PRD | User-stated requirements from deep-interview or conversation |
| ADR | Decision drivers stated in the ADR's Context section |
| Email / client report | Facts from session context or user-provided data |
| Wiki page | Library source file (PDF/EPUB path) |
| Slide content | Source document or user-stated outline |
If the document type does not match a known pattern, ask the user to declare sources
before running Pass 2. Do not guess at source material.
Anti-Patterns
Do not combine doc-review with code-review. They are separate passes with different criteria.
Do not skip Pass 2 because "the document looks reasonable." Plausible hallucinations are
the most dangerous kind.
Do not flag ungrounded claims as hallucinations. They are different: a hallucination
contradicts the source; an ungrounded claim has no source to contradict.
Mandatory Checklist
- Verify document type and sources were identified before any scoring
- Verify Presentation Pass scored all 4 dimensions (not just the failing ones)
- Verify Hallucination Pass checked every factual claim, not just obvious ones
- Verify ungrounded claims are listed separately from hallucinations
- Verify every REVISE or BLOCK finding has a location reference and specific fix
- Verify verdict is one of: PASS / REVISE / BLOCK
- Verify BLOCK was used for any hallucination that would mislead the reader
