doc-review

Description

Multi-agent documentation quality review system that analyzes a single file or all files in a folder for data inconsistencies, reference errors, typos, and unclear terminology.

Category

Quality Assurance

Complexity

High (multi-agent coordination)

Purpose

Comprehensive documentation quality review using specialized sub-agents to detect:

Data inconsistencies

Contradictory information, wrong data, confusing content

Reference errors

Broken links, invalid cross-references, missing anchors

Typos and spelling

Misspellings, grammatical errors, formatting issues

Terminology issues

Undefined terms, inconsistent naming, ambiguous language

Analysis Modes

Mode

Input

Behavior

Single File

/doc-review path/to/file.md

Analyzes one file in depth

Folder

/doc-review path/to/folder/

Analyzes ALL files in folder together, including cross-file consistency

Folder mode

provides additional cross-file checks:

Terminology consistency across all documents

Cross-document reference validation

Duplicate content detection across files

Consistent naming conventions

When to Use This Skill

Use doc-review when

:

Reviewing documentation before publication

Validating files after batch creation

Performing quality audits on markdown/YAML files

Checking cross-reference integrity

Pre-commit quality validation

Reviewing a single file or entire folder

Do NOT use when

:

Full traceability validation needed (use trace-check)

Code-specific review needed (use code-review)

Single document structure validation (use doc-*-validator skills)

Skill Inputs

Input

Type

Required

Description

Example

path

string

Yes

Single file path or folder path to review

ai_dev_flow/PRD/PRD-001.md

,

docs/EARS/

scope

string

No

Review scope

"full"

(default),

"quick"

,

"deep"

focus

array

No

Specific checks to run

["data", "references", "typos", "terms"]

report_format

string

No

Output format

"markdown"

(default),

"json"

,

"summary"

auto_fix

boolean

No

Attempt automatic fixes

false

(default)

Sub-Agent Architecture

The skill coordinates

4 specialized sub-agents

that run in parallel:

graph

TD

A

[doc-review Skill]

-->

B

[Input: File or Folder]

B

-->

C

[File Discovery]

C

-->

D

[Parallel Sub-Agents]

D

-->

E

[Data Consistency Agent]

D

-->

F

[Reference Checker Agent]

D

-->

G

[Typo Detection Agent]

D

-->

H

[Terminology Agent]

E

-->

I

[Merge Results]

F

-->

I

G

-->

I

H

-->

I

I

-->

J

[Generate Report]

J

-->

K

[Output: Quality Report]

Sub-Agent 1: Data Consistency Agent

Purpose

Detect inconsistent, wrong, or confusing information

Checks

:

Contradictory statements within same document

Numerical inconsistencies (counts, dates, versions)

Status field mismatches (metadata vs content)

Duplicate content with variations

Logical contradictions

Outdated information markers

Detection Patterns

:

data_consistency_checks

:

count_mismatch

:

pattern

:

"\d+ (requirements|items|sections)"

validate

:

"count matches actual items"

error_code

:

"DATA-E001"

status_mismatch

:

pattern

:

"Status:\s*(Draft|Approved|Implemented)"

validate

:

"matches content maturity"

error_code

:

"DATA-E002"

date_inconsistency

:

pattern

:

"\d{4}-\d{2}-\d{2}"

validate

:

"Last Updated >= Created"

error_code

:

"DATA-E003"

version_format

:

pattern

:

"Version:\s*[\d.]+"

validate

:

"semantic versioning compliance"

error_code

:

"DATA-E004"

duplicate_content

:

pattern

:

"similar paragraphs >80%"

validate

:

"intentional or error"

error_code

:

"DATA-W001"

Sub-Agent 2: Reference Checker Agent

Purpose

Validate all links, references, and cross-document connections Checks : Markdown link resolution ( text ) Internal anchor existence (

section-id

)

Cross-document reference validity

Relative path correctness

External URL accessibility (optional)

Traceability tag format (

@brd:

,

@prd:

, etc.)

Detection Patterns

:

reference_checks

:

broken_link

:

pattern

:

"\[.?\]\(.?\)"

validate

:

"target file exists"

error_code

:

"REF-E001"

invalid_anchor

:

pattern

:

"\[.?\]\(.?#.*?\)"

validate

:

"anchor exists in target"

error_code

:

"REF-E002"

orphan_anchor

:

pattern

:

"^#{1,6}\s+.*$"

validate

:

"has incoming references"

error_code

:

"REF-W001"

relative_path

:

pattern

:

"\.\./|\./"

validate

:

"path resolves correctly"

error_code

:

"REF-E003"

tag_format

:

pattern

:

"@(brd|prd|ears|bdd|adr|sys|req|spec|impl|ctr|tasks):"

validate

:

"follows TYPE.NN.TT.SS format"

error_code

:

"REF-E004"

circular_reference

:

pattern

:

"A→B→...→A"

validate

:

"no circular chains"

error_code

:

"REF-E005"

Sub-Agent 3: Typo Detection Agent

Purpose

Find spelling errors, grammatical issues, and formatting problems

Checks

:

Common misspellings

Technical term spelling

Capitalization inconsistencies

Punctuation errors

Whitespace issues

Markdown syntax errors

Detection Patterns

:

typo_checks

:

common_misspellings

:

dictionary

:

"en_US + technical_terms"

error_code

:

"TYPO-E001"

case_inconsistency

:

pattern

:

"same term, different cases"

examples

:

[

"GitHub/github"

,

"API/api"

,

"JavaScript/Javascript"

]

error_code

:

"TYPO-W001"

double_words

:

pattern

:

"\b(\w+)\s+\1\b"

error_code

:

"TYPO-E002"

markdown_syntax

:

patterns

:

-

"unclosed_code_block"

-

"mismatched_brackets"

-

"broken_table"

error_code

:

"TYPO-E003"

punctuation

:

patterns

:

-

"double_period: \.\."

-

"space_before_comma: \s,"

-

"missing_space_after_period: \.[A-Z]"

error_code

:

"TYPO-W002"

whitespace

:

patterns

:

-

"trailing_whitespace"

-

"multiple_blank_lines"

-

"tabs_vs_spaces"

error_code

:

"TYPO-W003"

Sub-Agent 4: Terminology Agent

Purpose

Identify unclear, undefined, or inconsistent terminology Checks : Undefined acronyms Inconsistent term usage Ambiguous language Jargon without definition Conflicting definitions Domain-specific term validation Detection Patterns : terminology_checks : undefined_acronym : pattern : "\b[A-Z]{2,}\b" validate : "defined on first use or in glossary" error_code : "TERM-E001" inconsistent_naming : examples : - "user/User/USER" - "login/sign-in/authenticate" - "config/configuration/settings" error_code : "TERM-E002" ambiguous_terms : flagged_words : - "it" - "this" - "that" - "they" context : "unclear antecedent" error_code : "TERM-W001" subjective_qualifiers : flagged_words : - "easy" - "simple" - "fast" - "efficient" - "powerful" context : "lacks quantification" error_code : "TERM-W002" undefined_jargon : pattern : "domain-specific terms without definition" error_code : "TERM-W003" conflicting_definitions : pattern : "same term, different meanings" error_code : "TERM-E003" Workflow Execution Step 1: File Discovery

Expand path/pattern to file list

def discover_files ( path_pattern ) : if is_glob_pattern ( path_pattern ) : return glob . glob ( path_pattern , recursive = True ) elif os . path . isfile ( path_pattern ) : return [ path_pattern ] elif os . path . isdir ( path_pattern ) : return glob . glob ( f" { path_pattern } /*/.md" , recursive = True ) else : raise FileNotFoundError ( f"Path not found: { path_pattern } " ) Step 2: Launch Parallel Sub-Agents

Launch 4 sub-agents in parallel using Task tool

async def run_review ( files , scope , focus ) : tasks = [ ] if "data" in focus or focus == "all" : tasks . append ( Task ( subagent_type = "general-purpose" , prompt = f"Review files for data consistency: { files } " , description = "Data consistency check" ) ) if "references" in focus or focus == "all" : tasks . append ( Task ( subagent_type = "general-purpose" , prompt = f"Validate all references and links: { files } " , description = "Reference validation" ) ) if "typos" in focus or focus == "all" : tasks . append ( Task ( subagent_type = "general-purpose" , prompt = f"Check for typos and formatting: { files } " , description = "Typo detection" ) ) if "terms" in focus or focus == "all" : tasks . append ( Task ( subagent_type = "general-purpose" , prompt = f"Validate terminology consistency: { files } " , description = "Terminology review" ) )

Run all tasks in parallel

results

await asyncio . gather ( * tasks ) return merge_results ( results ) Step 3: Merge and Prioritize Results def merge_results ( agent_results ) : merged = { "errors" : [ ] ,

Severity: ERROR (must fix)

"warnings" : [ ] ,

Severity: WARNING (should fix)

"info" : [ ] ,

Severity: INFO (consider)

"stats" : { } } for result in agent_results : merged [ "errors" ] . extend ( result . get ( "errors" , [ ] ) ) merged [ "warnings" ] . extend ( result . get ( "warnings" , [ ] ) ) merged [ "info" ] . extend ( result . get ( "info" , [ ] ) )

Deduplicate and sort by severity

merged [ "errors" ] = deduplicate ( merged [ "errors" ] ) merged [ "warnings" ] = deduplicate ( merged [ "warnings" ] ) return merged Step 4: Generate Report Output format based on report_format parameter. Error Codes Reference Data Consistency (DATA) Code Severity Description Auto-Fix DATA-E001 ERROR Count mismatch (stated vs actual) Yes DATA-E002 ERROR Status/content maturity mismatch Manual DATA-E003 ERROR Date inconsistency Yes DATA-E004 ERROR Invalid version format Yes DATA-W001 WARNING Potential duplicate content Manual DATA-W002 WARNING Outdated information marker Manual References (REF) Code Severity Description Auto-Fix REF-E001 ERROR Broken link (file not found) Manual REF-E002 ERROR Invalid anchor Manual REF-E003 ERROR Relative path error Yes REF-E004 ERROR Invalid traceability tag format Yes REF-E005 ERROR Circular reference detected Manual REF-W001 WARNING Orphan anchor (no incoming refs) Manual Typos (TYPO) Code Severity Description Auto-Fix TYPO-E001 ERROR Misspelled word Yes TYPO-E002 ERROR Double word Yes TYPO-E003 ERROR Markdown syntax error Manual TYPO-W001 WARNING Case inconsistency Manual TYPO-W002 WARNING Punctuation issue Yes TYPO-W003 WARNING Whitespace issue Yes Terminology (TERM) Code Severity Description Auto-Fix TERM-E001 ERROR Undefined acronym Manual TERM-E002 ERROR Inconsistent term usage Manual TERM-E003 ERROR Conflicting definitions Manual TERM-W001 WARNING Ambiguous pronoun Manual TERM-W002 WARNING Subjective qualifier Manual TERM-W003 WARNING Undefined jargon Manual Usage Examples Example 1: Review Single File /doc-review ai_dev_flow/EARS/EARS_CREATION_RULES.md Output : === Documentation Review Report === File: ai_dev_flow/EARS/EARS_CREATION_RULES.md Mode: Single File Scope: full Data Consistency: 2 issues [DATA-E001] Line 547: States "total_requirements: 135" but only 130 found [DATA-W001] Line 89-95: Similar content to lines 105-111 References: 1 issue [REF-E002] Line 137: Anchor #cross-reference-link-format-mandatory not found Typos: 0 issues Terminology: 1 issue [TERM-W002] Line 26: "Complete reference" - subjective qualifier Summary: 4 issues (2 errors, 2 warnings) Example 2: Review All Files in Folder /doc-review docs/EARS/ Output : === Documentation Review Report === Folder: docs/EARS/ Mode: Folder (all files together) Files analyzed: 12 Scope: full Cross-File Analysis: [TERM-E002] Inconsistent term: "requirement" vs "EARS requirement" across 4 files [REF-E001] Broken cross-reference: EARS-001.md → EARS-005.md#section-missing Per-File Issues: EARS-001.md: 2 errors, 1 warning EARS-002.md: 0 errors, 3 warnings ... Summary: 8 errors, 15 warnings across 12 files Example 3: Focus on Specific Checks /doc-review ai_dev_flow/PRD/ --focus references,typos Example 4: Quick Pre-Commit Check /doc-review docs/ --scope quick --report_format summary Output : Quick Review: docs/ Files scanned: 87 Errors: 3 Warnings: 12 Status: NEEDS ATTENTION (fix errors before commit) Integration Points With Other Skills Skill Integration trace-check Shares reference validation logic doc-validator Complementary (cross-doc vs single-file) quality-advisor Real-time vs batch validation code-review Source code vs documentation focus With CI/CD

.github/workflows/docs-review.yml

name : Documentation Review on : [ pull_request ] jobs : doc-review : runs-on : ubuntu - latest steps : - uses : actions/checkout@v3 - name : Run doc review run : | claude-code /doc-review docs/ --scope quick --report_format json > review.json - name : Check for errors run : | if jq '.errors | length > 0' review.json; then echo "Documentation errors found" exit 1 fi Quality Gates Definition of Done All ERROR-level issues resolved WARNING-level issues reviewed and addressed or justified No broken links All acronyms defined Terminology consistent across documents No typos in headers or critical content Severity Thresholds Scope Errors Allowed Warnings Allowed quick 0 10 full 0 5 deep 0 0 Sub-Agent Prompts Data Consistency Agent Prompt You are a data consistency reviewer. Analyze the following file(s) for: 1. Count Mismatches: Find stated counts that don't match actual items - "N requirements" should match actual requirement count - "N sections" should match actual section count 2. Status Inconsistencies: Check metadata vs content alignment - Status: Approved but content has TBD markers - Version mismatches between header and changelog 3. Date Inconsistencies: Validate date logic - Last Updated should be >= Created date - Referenced dates should be valid 4. Duplicate Content: Flag similar paragraphs that may be errors Output format: JSON with error_code, line_number, description, severity Reference Checker Agent Prompt You are a reference validation expert. Analyze the following file(s) for: 1. Broken Links: Verify all markdown links resolve - text - file exists - text - anchor exists 2. Invalid Cross-References: Check traceability tags - @brd: BRD.NN.TT.SS format - @prd: PRD.NN.TT.SS format - Document referenced must exist 3. Relative Path Errors: Validate ../ paths resolve correctly 4. Orphan Anchors: Find headers with no incoming links (optional) Output format: JSON with error_code, line_number, target, description, severity Typo Detection Agent Prompt You are a proofreading expert. Analyze the following file(s) for: 1. Spelling Errors: Common misspellings and technical terms - Use standard English dictionary + technical glossary - Flag words not in either 2. Markdown Syntax: Validate proper formatting - Unclosed code blocks - Mismatched brackets/parentheses - Broken table syntax 3. Punctuation Issues: Common punctuation errors - Double periods, missing spaces after periods - Comma usage 4. Whitespace Problems: Formatting consistency - Trailing whitespace - Multiple blank lines - Inconsistent indentation Output format: JSON with error_code, line_number, word/pattern, suggestion, severity Terminology Agent Prompt You are a terminology consistency expert. Analyze the following file(s) for: 1. Undefined Acronyms: Find uppercase abbreviations without definitions - Check if defined on first use - Check if in glossary section 2. Inconsistent Naming: Same concept, different names - user/User/USER - login/sign-in/authenticate - Build term consistency map 3. Ambiguous Language: Unclear references - Pronouns with unclear antecedents (it, this, that) - Vague quantifiers (some, many, few) 4. Subjective Qualifiers: Unmeasurable claims - "easy to use", "fast", "efficient" - "simple configuration" Output format: JSON with error_code, line_number, term, issue, suggestion, severity Configuration Custom Dictionary Add project-specific terms to skip false positives:

.doc-review.yaml

custom_dictionary : - "EARS" - "BDD" - "ADR" - "Gherkin" - "SDD" - "traceability" ignored_patterns : - "node_modules/" - "*.min.js" - "vendor/" severity_overrides : TERM-W002 : "INFO"

Downgrade subjective qualifiers to INFO

Performance

Benchmarks

Files

Scope

Time

Memory

10

quick

<5s

50MB

50

full

<30s

200MB

100

deep

<60s

400MB

Optimization

Parallel sub-agents reduce wall-clock time by ~60%

Caching of dictionary lookups

Incremental mode for changed files only

Limitations

Cannot understand semantic meaning deeply (may miss logical contradictions)

May produce false positives for domain-specific terminology

External URL validation requires network access

Auto-fix limited to simple patterns (typos, formatting)

Complex reference chains require manual review

Version Information

Version

1.0.0

Created

2026-01-01

Status

Active

Author

AI Dev Flow Framework Change Log : 1.1.0 (2026-01-01): Renamed to doc-review, clarified analysis modes Single file mode: deep analysis of one file Folder mode: analyze all files together with cross-file checks Added cross-file consistency checks in folder mode 1.0.0 (2026-01-01): Initial release as file-review with 4 sub-agents Data consistency checking Reference validation Typo detection Terminology review Parallel execution support Multiple output formats