title	doc-review: Multi-agent documentation quality review
name	doc-review
description	Review a single file or all files in a folder for data inconsistencies, reference errors, typos, and unclear terminology using parallel sub-agents
tags	quality-assurance, shared-architecture, multi-agent, validation, documentation
custom_fields	[object Object]
version	1.1.0
document_control	[object Object]

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](path#anchor))
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|iplan):"
    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](path) - file exists
   - [text](path#anchor) - 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

Install Skill

SKILL.md

doc-review

Purpose

Analysis Modes

When to Use This Skill

Skill Inputs

Sub-Agent Architecture

Sub-Agent 1: Data Consistency Agent

Sub-Agent 2: Reference Checker Agent

Sub-Agent 3: Typo Detection Agent

Sub-Agent 4: Terminology Agent

Workflow Execution

Step 1: File Discovery

Step 2: Launch Parallel Sub-Agents

Step 3: Merge and Prioritize Results

Step 4: Generate Report

Error Codes Reference

Data Consistency (DATA)

References (REF)

Typos (TYPO)

Terminology (TERM)

Usage Examples

Example 1: Review Single File

Example 2: Review All Files in Folder

Example 3: Focus on Specific Checks

Example 4: Quick Pre-Commit Check

Integration Points

With Other Skills

With CI/CD

Quality Gates

Definition of Done

Severity Thresholds

Sub-Agent Prompts

Data Consistency Agent Prompt

Reference Checker Agent Prompt

Typo Detection Agent Prompt

Terminology Agent Prompt

Configuration

Custom Dictionary

Performance

Benchmarks

Optimization

Limitations

Version Information