docs-align

Docs Align

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

Workflow

Read the repo AGENTS.md.
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>
python3 scripts/docs_drift.py compare --input <json> --out <json>
Render the summary:
- python3 scripts/docs_drift.py render --input <json> --format md
Use Alignment policies below only for doc surfaces that the gap map says are in scope.
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