# Doc Review

> Dual-dimension document quality gate — presentation rubric + hallucination grounding check

- Skill: `andrem-sec/doc-review` (Agent Skill)
- Install (CLI): `npx skillmds@latest add andrem-sec/doc-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/andrem-sec/doc-review/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: andrem-sec (https://skillmd.com/u/andrem-sec)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/andrem-sec/doc-review

---


# 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:

1. Generate a brief overview (title, 3-5 bullet points, sources list) first
2. Present the overview to the user for confirmation
3. 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:

1. Identify the source it should be grounded in (stated explicitly or inferable from context)
2. Verify the claim against that source
3. 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

1. Verify document type and sources were identified before any scoring
2. Verify Presentation Pass scored all 4 dimensions (not just the failing ones)
3. Verify Hallucination Pass checked every factual claim, not just obvious ones
4. Verify ungrounded claims are listed separately from hallucinations
5. Verify every REVISE or BLOCK finding has a location reference and specific fix
6. Verify verdict is one of: PASS / REVISE / BLOCK
7. Verify BLOCK was used for any hallucination that would mislead the reader