Docs Align

Use this skill after implementation work or when you suspect documentation drift.

Workflow

1. Read the repo AGENTS.md.
2. From this skill root (directory containing SKILL.md), run drift collection (requires git on PATH):

• python3 scripts/docs_drift.py collect --cwd <repo> --out <json>
• Equivalent collect-only shortcut: python3 scripts/check_docs_drift.py --cwd <repo> --out <json>

1. python3 scripts/docs_drift.py compare --input <json> --out <json>
2. Render the summary:

• python3 scripts/docs_drift.py render --input <json> --format md

1. Use Alignment policies below only for doc surfaces that the gap map says are in scope.
2. Update docs only after the gap map is clear.

Path note

Commands above assume the current working directory is this skill’s root (skills/docs-align in this repository). If the working directory is elsewhere, invoke the same files with an absolute path, for example:

python3 "<skill-dir>/scripts/docs_drift.py" collect --cwd <repo> --out <json>

Alignment policies

ADR

Create or update an ADR when the implementation changed:

• architecture boundaries
• execution model
• durable workflow policy
• major dependencies or infrastructure choices

Do not create ADR churn for small local refactors.

Spec

Update product or architecture specs when the implementation changed:

• interfaces
• contracts
• verification steps
• operational behavior

Prefer deleting stale spec text over leaving contradictory guidance.

README

Update the README when the change affects:

• setup
• commands
• environment variables
• high-level architecture or usage expectations

Keep the README high signal; move deep details into docs when needed.

Use When

• The task is post-implementation doc alignment.
• The user wants README, ADR, spec, or AGENTS updates based on code changes.

Do Not Use When

• The task is only code review remediation.
• The task is only dependency planning.

Outputs

• likely impacted docs
• missing/update/delete doc tasks
• a concise docs alignment summary