BjornMelin 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 (requiresgiton 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