Review Doc Consistency

What it does

This skill, Review Doc Consistency, systematically identifies inconsistencies between documentation and code within a project's README and documentation files (located in docs/**/*.md). It prioritizes discrepancies where documentation conflicts with source code, configuration files, or contract definitions (like OpenAPI/proto/schema/TS types), treating these as the single source of truth. The skill aims to output at least 30 identified issues, categorized by severity, and provides evidence for each finding.

When to use it

• Maintaining accurate API documentation: Ensure your API documentation accurately reflects the current code implementation.
• Validating development guides: Confirm that instructions in development guides are consistent with how the code actually works.
• Improving security posture: Identify and address any inconsistencies related to security configurations documented versus implemented.
• Standardizing project documentation: Enforce consistency across all documents, including READMEs and API references.

Key capabilities

• Document Scanning: Scans README.md (root directory) and files within the docs/**/*.md directories, as well as contract files (OpenAPI/proto/GraphQL schema/TS types).
• Code-Documentation Comparison: Compares documentation claims with corresponding code implementations to identify mismatches in behavior, default values, or missing information.
• Severity Level Assignment: Categorizes issues based on severity levels: P0 (Security/Serious Misleading), P1 (Core Functionality Inconsistency), P2 (Incomplete Examples/Naming), P3 (Minor Wording Issues), and Pending Evidence.
• Evidence-Based Reporting: Provides specific code or configuration file locations as evidence for each identified inconsistency.
• Output Formatting: Generates a doc-consistency.md report file and a structured doc-consistency.json issue list.

Example prompts

• "Review the documentation for inconsistencies with the codebase."
• "Check all API documentation against the OpenAPI schema."
• "Find any discrepancies between the README and the current code implementation."

Tips & gotchas

• Contracts are authoritative: Remember that contract files (OpenAPI, proto, etc.) take precedence over documentation.
• Prioritization: Security-related inconsistencies (P0 severity) will be prioritized.
• Parallel Execution: The skill is designed to be run in parallel across different document types or modules for faster review times.