doc-review

doc-review

Perform adversarial comparison of documentation content against context sources to detect inaccuracies, omissions, and hallucinations.

Prerequisites

• AsciiDoc files to review (specified in arguments)
• workspace/context-package.json should exist for cross-reference checking

Parse arguments

$ARGUMENTS contains:

1. Target: file path, directory, or glob pattern for AsciiDoc files to review
2. --context (optional): path to context package (defaults to workspace/context-package.json)

Step 1: Discover files

Resolve the target to a list of .adoc files:

• Single file: review that file
• Directory: glob **/*.adoc
• Glob pattern: expand it

Step 2: Load context

Read workspace/context-package.json and extract:

• Ticket metadata (summary, description, components)
• Context files with content (source code, API specs, architecture docs, existing docs)
• Product conventions

Group context files by type for targeted comparison:

• Source code: .go, .py, .java files — authoritative for API behavior
• API specs: *_types.go, *.yaml CRD files — authoritative for field names and schemas
• Architecture docs: .md files from architecture repos — authoritative for design
• Existing docs: .adoc files — reference for style and terminology

Step 3: Review each file

For each AsciiDoc file, read its content and construct a review prompt combining:

1. Read ${CLAUDE_SKILL_DIR}/prompts/review-content.md template
2. The documentation content being reviewed
3. Relevant context files (matched by topic/component)
4. Ticket metadata

Ask the LLM to perform adversarial review:

• Factual accuracy: Compare every technical claim against source code and API specs
• Completeness: Check if important details from the ticket and context are covered
• Consistency: Verify terminology matches existing documentation
• Hallucination check: Flag any API fields, CLI flags, config options, or behaviors not found in context sources