flake-update-20260505

name: docs-drift-review description: Analyze repository documentation for implementation drift, stale examples, missing coverage, and reorganization opportunities. USE WHEN user says ‘review docs’, ‘docs drift’, ‘stale docs’, ‘doc audit’, ‘check docs’, or wants to compare documentation against implementation.

Docs Drift Review

Audit documentation against the actual implementation. Find stale content, missing coverage, and correctness issues. Produce a prioritized report with exact file references and proposed fixes.

Non-Goals

  • Don’t invent behavior not supported by code or tests
  • Don’t rewrite all docs when a targeted patch is enough
  • Don’t flag style preferences as defects unless they reduce clarity
  • Don’t modify files unless the user explicitly asks for edits

Workflow

Step 1: Build a Docs Map

Create a compact inventory:

  • Major doc files and their purpose
  • Feature areas covered
  • Source-of-truth files for each area
  • Stale-looking sections (versioned commands, flags, env vars, API paths, copied outputs)

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, 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 or prerequisites
  • Outdated examples or sample outputs
  • Undocumented new behavior
  • Docs claiming support that code no longer provides
  • Missing constraints, edge cases, or failure modes

For each suspected drift: find exact evidence in docs AND in code/tests. Classify as confirmed, likely, or insufficient evidence.

Step 4: Review Doc Quality

Check for:

  • Spelling and grammar errors
  • Inconsistent naming of products, features, commands
  • Ambiguous wording, duplicate content
  • Examples without explanation or explanation without examples
  • Missing cross-links, outdated file path references

Step 5: Produce Prioritized Report

Severity Guide

Level Criteria
critical Setup-breaking, security-relevant, migration-breaking, or API-breaking doc errors
high Materially misleading docs that waste time or cause wrong usage
medium Missing context, stale examples, structural issues
low Spelling, grammar, naming consistency, polish

Output Format

### Summary
- Overall docs health
- Count of findings by severity
- Top 3 issues

### Findings
For each finding:
- ID, Severity, Confidence (confirmed/likely/uncertain)
- Docs evidence (file:line)
- Implementation evidence (file:line)
- Why this matters
- Recommended fix

### Coverage Gaps
Feature areas implemented but not documented.

### Quick Wins
Smallest high-value doc fixes.

Evidence Rules

  • Prefer direct evidence from code, tests, schemas, generated help
  • If behavior is ambiguous, say so explicitly
  • Don’t infer runtime behavior solely from type names or comments
  • If tests contradict docs, treat as drift signal and note the contradiction

Common Drift Patterns

  • README says one command, CLI help exposes another
  • Docs list flags not in parser definitions
  • Docs omit required env vars now enforced by code
  • Examples use old API paths or field names
  • Docs describe defaults that changed in config
  • Docs refer to moved files or directories
  • Generated CRDs changed but prose docs didn’t
  • CodeReview: For code quality review (not docs)
  • DocCoauthoring: For writing new documentation