/md-reviewer

Summary

Docs drift — terms shift, cross-references rot, contradictions accumulate. /md-reviewer audits Markdown for consistency, contradictions, and stale links before readers find them. Handles sets of 50+ files with resumable progress tracking, and validates follower docs against an authoritative master.

When to use

Use /md-reviewer when docs have grown beyond what you can eyeball — terminology has drifted, you suspect contradictions between pages, or cross-references may have gone stale after a rename. It covers: terminology consistency, logical contradictions, cross-reference validity, formatting standards, voice/tone analysis, technical accuracy, and duplicate detection.

Trigger phrases (from SKILL.md):

• "review my documentation"
• "check docs for inconsistencies"
• "validate markdown files"
• "find contradictions in docs"
• "audit documentation quality"

Master-follower mode: nominate one doc as the authority (e.g. README.md) and all others are checked against it. Findings are tagged by severity — contradiction, drift, stale ref, formatting.

Invocation

Invoke directly, then describe the docs to review — or paste file paths:

/md-reviewer

The skill asks two setup questions before starting: which files to review, and whether one file is the authoritative master. For large sets (50+ files), it tracks progress so you can pause and resume without restarting.

Example 1 — Master-follower review

/md-reviewer
check docs/ for inconsistencies — README.md is the master

Setup
────────
Master: README.md
Followers: docs/architecture.md, docs/api.md, docs/install.md (3 files)

Processing README.md as master... done.
Processing followers (1/3): docs/architecture.md... done.
Processing followers (2/3): docs/api.md... done.
Processing followers (3/3): docs/install.md... done.

Findings (3)
────────────────────────────────────────────────────────
File                  Line  Severity     Issue
────────────────────────────────────────────────────────
docs/architecture.md  14    Drift        Uses "item"; README uses "task" for same concept
docs/api.md           52    Stale ref    Links to /docs/config.md — file was renamed to /docs/setup.md
docs/install.md       88    Contradiction Says Node 18+ required; README says Node 20+
────────────────────────────────────────────────────────

3 issues found across 3 files.

Example 2 — Small-set contradiction check

/md-reviewer check CLAUDE.md, release-guide.md, and release.sh comments for contradictions

Reviewing 3 files (no master nominated — cross-checking all pairs).

Findings (1)
────────────────────────────────────────────────────────
File        Line  Severity       Issue
────────────────────────────────────────────────────────
release.sh  34    Contradiction  Comment says "--dry-run prints nothing"; release-guide.md
                                 says it "prints the planned steps and exits 0"
────────────────────────────────────────────────────────

1 issue found.

Related tools

• /documentation-standard — Enforces doc structure: where files go, what sections to include. Run before /md-reviewer to get structure right first.
• /doc-voice — Governs prose voice: problem-first, proof-led, no marketing fluff. Fixes the writing style /md-reviewer flags as voice-drift.
• /da-review — Adversarial one-pass review; use it after /md-reviewer when you want a second opinion on whether the fixes are sound.