| name | docs-drift-review |
| description | Analyze repository documentation for implementation drift, stale examples, missing coverage, spelling/clarity issues, and reorganization opportunities; produce a prioritized report with exact file references and proposed fixes. |
| version | 1.0.0 |
Docs Drift Review
Purpose
Use this skill when the user asks to:
- compare docs with the implementation
- find stale or incorrect docs
- review README, guides, API docs, design docs, comments, or onboarding docs
- suggest documentation improvements
- identify spelling, grammar, naming consistency, or reorganization issues
- prepare a documentation cleanup plan
- verify whether a feature or interface changed without corresponding docs updates
Outcomes
Produce a report that:
- Identifies implementation drift between docs and code.
- Distinguishes confirmed issues from plausible-but-unverified concerns.
- Suggests precise improvements to wording, examples, spelling, structure, and navigation.
- Prioritizes findings by user impact.
- Recommends the smallest sensible patch set.
Non-goals
Do not:
- invent behavior not supported by code or tests
- rewrite all docs when a targeted patch is enough
- flag style preferences as defects unless they reduce clarity or conflict with repo conventions
- claim drift based only on naming differences without checking surrounding context
- modify files unless the user explicitly asks for edits
Inputs to inspect
Prefer to inspect, in this order:
AGENTS.md and nearby agent instructions- top-level
README*
- docs directories such as
docs/, documentation/, guides/, examples/
- API specs and schemas such as OpenAPI, JSON Schema, protobuf, CRDs, GraphQL schema
- source code implementing the documented behavior
- tests covering the documented behavior
- config files, CLI help text, and sample manifests
- changelogs, migration guides, release notes
Core workflow
Step 1: Build a docs map
Create a compact inventory:
- major doc files and their purpose
- feature areas covered
- likely source-of-truth files for each area
- stale-looking sections such as versioned commands, flags, env vars, API paths, screenshots, copied outputs, or step-by-step flows
Step 2: Build an implementation map
Identify:
- entrypoints
- public interfaces
- commands, flags, config keys, env vars
- API routes, request/response shapes
- feature gates, defaults, constraints
- examples and fixtures
- relevant tests
Prefer tests and schemas over comments when determining current behavior.
Step 3: Compare docs against implementation
Check for:
- renamed or removed commands, flags, env vars, config fields, APIs
- changed defaults
- changed prerequisites or setup steps
- outdated examples or sample outputs
- undocumented new behavior
- docs claiming support that code no longer provides
- docs omitting constraints, edge cases, or failure modes that matter in practice
For each suspected drift item:
- find exact evidence in docs
- find exact evidence in code/tests/specs
- decide: confirmed drift, likely drift, or insufficient evidence
Step 4: Review doc quality
Inspect for:
- spelling and grammar errors
- inconsistent naming of products, features, commands, files, or concepts
- ambiguous wording
- duplicate content across files
- weak information architecture
- sections in the wrong place
- poor scannability
- examples without explanation
- explanation without runnable examples
- missing cross-links
- outdated references to file paths or repo layout
Step 5: Produce a prioritized report
Organize findings into:
- Critical correctness issues
- Important missing or stale content
- Clarity and usability improvements
- Copyediting issues
- Reorganization proposals
For each finding include:
- severity: critical / high / medium / low
- confidence: confirmed / likely / uncertain
- docs file(s)
- implementation file(s)
- concise explanation
- recommended fix
- optional proposed replacement text
Severity guide
Use:
- critical for setup-breaking, security-relevant, migration-breaking, or API-breaking documentation errors
- high for materially misleading docs that waste time or cause wrong usage
- medium for missing context, omissions, stale examples, or structural issues that impair success
- low for spelling, grammar, naming consistency, and polish
Evidence rules
- Prefer direct evidence from code, tests, schemas, generated help, or examples.
- If behavior is ambiguous, say so explicitly.
- Do not infer runtime behavior solely from type names or comments.
- If tests contradict prose docs, treat that as a drift signal and note the contradiction.
- If docs contradict code but code appears accidental or buggy, do not decide policy; report the mismatch neutrally.
Output format
Use this structure:
Summary
- brief statement of overall docs health
- count of findings by severity
- top 3 issues
Findings
For each finding:
- ID
- Severity
- Confidence
- Docs evidence
- Implementation evidence
- Why this matters
- Recommended fix
- Proposed text (only when helpful)
Coverage gaps
List feature areas implemented but not documented.
Reorganization suggestions
Suggest merges, splits, moves, or index pages.
Quick wins
List the smallest high-value doc fixes.
Optional patch plan
If the user asked for edits, propose a safe file-by-file sequence.
Review heuristics
Look especially for these drift patterns:
- README says one command, CLI help exposes another
- docs list flags not present in parser definitions
- docs omit required env vars or credentials now enforced by code
- examples use old API paths or field names
- docs describe defaults that changed in config code
- migration guides no longer match actual upgrade path
- docs refer to directories or files moved in the repo
- generated artifacts or CRDs changed but prose docs did not
- screenshots or output snippets no longer match current UX or logs
Spelling and style heuristics
Flag:
- repeated words
- obvious spelling mistakes
- inconsistent capitalization of product names
- inconsistent code font for commands, filenames, flags, env vars
- headings that do not match the section content
- paragraphs that should be converted into steps, tables, or bullet lists
- long pages that need a TOC or subsection split
Do not overcorrect for house style unless a local convention is clear.
Reorganization heuristics
Suggest reorganization when:
- the same concept is explained in 3 or more places
- onboarding and reference material are mixed together
- migration guidance is buried in release notes
- examples are detached from the feature they demonstrate
- the top-level README is doing too much
- there is no single source of truth for configuration or API reference
When asked to edit
If the user wants changes:
- edit the highest-severity correctness issues first
- then fix stale examples and missing prerequisites
- then improve naming consistency and structure
- keep diffs minimal and reviewable
- preserve established terminology unless the repo clearly moved on
Suggested prompts
Examples of requests this skill should handle:
- "Review the docs for implementation drift."
- "Compare README and docs/ against the current CLI and config."
- "Find stale examples and propose fixes."
- "Audit API docs versus the server implementation."
- "Suggest doc reorganization and copyediting improvements."
Completion criteria
The task is complete when:
- the main doc surfaces were checked against the current implementation
- findings are evidence-based and prioritized
- the report clearly separates confirmed issues from guesses
- suggested fixes are concrete enough to implement
