align-documentation

name	align-documentation
description	Audit and update existing documentation so it matches the current codebase — in-place updates only, no new files. Use when asked to "align the docs", "update documentation", "fix stale docs", "sync docs with code", or "check docs accuracy". Technology-agnostic.
metadata	{"author":"olivomarco","version":"1.0.0","argument-hint":"<docs-path-or-glob>"}

Align Documentation with the Codebase

Mission

Audit existing documentation and update any content that is stale, incorrect, or missing relative to the actual codebase. Do NOT create new files — only edit existing ones, in place. Do NOT change source code — docs only.

Scope & Preconditions

• Discover the docs to audit: by default README*, files under docs/, and other Markdown/docs the user points to. If the user provides a path or glob, use exactly that. These are the only files you may touch.
• Infer the stack so you can read the right source files when verifying claims.
• If a doc references an external framework/library and you're unsure what's current, consult authoritative up-to-date sources (official docs / a docs MCP tool) before judging correctness.

Workflow

1. Discover all docs — List every doc file in scope. These are the only files you may edit.
2. Read the codebase — For each doc, identify the features, APIs, commands, or patterns it describes, then read the relevant source to learn the current state.
3. Diff doc vs. code — For each doc, note every discrepancy:
   • Outdated API signatures, import paths, or commands
   • Removed or renamed files/functions/modules/entities
   • Missing coverage of features that already exist in the code
   • Wrong instructions (wrong command, wrong config, wrong convention)
4. Update in place — Edit each doc to fix the discrepancies. Keep the existing structure and tone. Remove only what is factually wrong; preserve still-valid context and rationale.
5. Report — After all edits, output a summary table.

Output Expectations

After making edits, output:

Summary Table

File	Changes made
docs/FOO.md	Updated X, removed Y, added note about Z

If a doc was already accurate, record "No changes needed".

Constraints

• Do NOT create any new file anywhere.
• Do NOT delete any existing doc file.
• Do NOT change source code — documentation only.
• Do NOT reformat for style alone; only change content that is factually wrong or missing.
• Preserve each doc's existing voice, structure, and conventions.
• Verify every change against the actual code before writing it; do not guess.