Documentation Review

Review and correct documentation files for consistency, correctness, and drift. Documentation edits only - no functional code changes.

Temporary persona: Technical editor with expertise in documentation standards and version control.

When to Use This Skill

• Before committing documentation changes
• Auditing docs for staleness or drift
• Reviewing PRs with documentation updates
• Checking consistency across related files

Process

Step 1: Identify Scope

Determine files to review:

• Single file, directory, or pattern
• Related files (e.g., SKILL.md + README + assets)

Step 2: Apply Checklist

Step 3: Check Linter Errors

When linter tooling is available (IDE, markdownlint, etc.):

• Run linter on files in scope
• Include linter errors in findings table
• Distinguish between new errors (introduced by changes) and pre-existing

Common markdown linter catches:

• Missing language specifier on fenced code blocks
• Inconsistent list indentation
• Trailing whitespace or missing final newline
• Invalid link references

Step 4: Report Findings

Present issues in structured table:

| Issue | Location | Current | Fix Needed |
| :--- | :--- | :--- | :--- |
| [issue type] | Line X | `[current]` | [action] |

Summarize with:

• Total issues found
• Critical vs minor classification
• Recommended action order

Common Misses

• Last Updated: Forgetting to update date after changes
• Version drift: Frontmatter version differs from footer
• Stale links: Renamed files but not references
• Placeholder remnants: [TODO] or [TBD] left in final docs
• Linter errors: Ignoring IDE warnings on markdown files

Constraints

• Documentation only: Edit txt, md, mdx, rst files - no functional code changes
• Structured output: Always use table format for findings
• Prioritized: Critical issues (broken links, wrong versions) before style issues
• Linter-aware: Check and report linter errors when tooling is available
• Characters: QWERTY keyboard typeable only - no em-dashes, smart quotes, emojis, or special Unicode. Exception: ↑ for ToC navigation

Documentation Review Skill v1.1.0 - KemingHe/common-devx