validate-docs-implementation_skill

Overview

This skill systematically compares implementation code against documentation to find and fix inconsistencies. It automates inspection of what the code actually creates or does, locates all doc references, applies precise updates, and produces a verification report. The result is documentation that matches the running implementation and reduces user confusion.

How this skill works

The skill reads the implementation files you point to and builds a ground-truth list of artifacts and behaviors (files, folders, counts, naming conventions). It then searches documentation for references to those entities, categorizes mismatches (file name, structure, count, deprecated references), and applies safe edits to update docs. Finally it verifies that old terms are gone and saves a report summarizing all fixes.

When to use it

• Before a release or deployment to ensure docs reflect the shipped behavior
• After major code changes or refactors that could affect outputs or structure
• When users report docs that mention missing or renamed files/folders
• During documentation audits or QA checks for consistency
• When preparing public guides, tutorials, or onboarding materials

Best practices

• Be systematic: analyze implementation first, then search docs exhaustively with pattern searches
• Preserve context: update surrounding text and examples when changing names or structure
• Prioritize fixes: address user-facing and core-system docs first
• Verify edits: re-run searches for old terms and spot-check updated files
• Record results: save validation reports to a configured location for traceability

Example use cases

• A script now creates plan.md instead of design.md — update all docs to use plan.md and remove obsolete references
• Project folder structure changed; update diagrams, README sections, and navigation maps to match new folders
• A generator now creates additional resource files — update counts and example lists across docs
• Pre-release sweep: verify no docs reference deprecated features or old file names before publishing
• User flags mismatch in tutorial steps; run targeted validation and push corrections with a report