ls-documentation-alignment

name	ls-documentation-alignment
description	Run automated repo documentation alignment: discover source truth, audit public/internal docs, refresh generated artifacts, coordinate subagent research, and verify docs in one pass.
metadata	{"version":"1.0"}
compatibility	Python 3.12+, PyYAML, Localsetup docs_alignment.py adapter. Generic workflow with Localsetup source-truth defaults.

Documentation alignment

Use this skill when a repo needs documentation brought back into alignment with the code, manifests, CLI commands, assets, generated docs, and current external documentation standards.

Purpose

• Discover source-of-truth surfaces before editing docs.
• Use subagents for independent repo scouting and current external research when the task is broad.
• Generate a stable inventory, truth map, audit result, asset manifest, and summary.
• Fix supported stale facts in public docs without hand-maintaining volatile counts.
• Keep generated docs owned by the repo generator instead of ad hoc edits.
• Record public-doc ownership through owner_skill or owner_package frontmatter and fail CI for active framework docs without an owner.
• Leave a reproducible validation trail for future runs.

Generic workflow

1. Create or resume a run ledger under .codex/runs/.
2. Inventory the repo: public docs, internal docs, generated docs, skills/workflows, assets, CLI commands, CI, and lifecycle metadata.
3. Map truth sources. For Localsetup, defaults are VERSION, pyproject.toml, _localsetup/config/*.yaml, _localsetup/skills/*/SKILL.md, _localsetup/workflows/*/workflow.yaml, generated facts, assets, and CI workflows.
4. Delegate scouts when scope is broad:
   • code truth and generator ownership
   • public docs and stale claims
   • internal/generated docs and lifecycle rules
   • current external documentation standards
   • assets and CI gates
   • skill/workflow package conventions
5. Run the alignment audit and plan. Treat subagent reports as evidence, not completion.
6. Apply generated and supported public fixes. Keep manual-review findings explicit.
7. Regenerate docs artifacts and run validation.
8. Run a final read-only review before claiming completion.

Commands

Inventory:

uv run --locked python _localsetup/tools/docs_alignment.py --repo-root . inventory

Audit:

uv run --locked python _localsetup/tools/docs_alignment.py --repo-root . audit

Plan:

uv run --locked python _localsetup/tools/docs_alignment.py --repo-root . plan

Apply generated artifacts:

uv run --locked python _localsetup/tools/docs_alignment.py --repo-root . apply --scope generated

Apply supported public-doc fixes:

uv run --locked python _localsetup/tools/docs_alignment.py --repo-root . apply --scope public

Dry-run any write scope:

uv run --locked python _localsetup/tools/docs_alignment.py --repo-root . apply --scope all --dry-run

CI/read-only check:

uv run --locked python _localsetup/tools/docs_alignment.py --repo-root . check --ci

Localsetup wrapper:

uv run --locked python _localsetup/tools/localsetup.py --source-root . docs-align check --ci

Outputs

Generated artifacts live under _localsetup/docs/_generated/:

• docs-inventory.json
• docs-truth-map.json
• docs-audit-result.json
• docs-asset-manifest.json
• docs-alignment-summary.md

Asset provenance and reference notes live in assets/README.md when the asset scope is applied.

Audit model

The tool reports JSON-first findings for:

• version and generated-facts drift
• stale generated skill taxonomy
• stale skill/workflow counts
• missing lifecycle frontmatter in framework docs
• missing or invalid active-doc ownership frontmatter
• broken relative links and missing image files
• missing image alt text
• unclosed fenced code blocks
• missing managed generated facts blocks

Critical and major findings fail check --ci.

Subagent pattern

For a generic repo, assign scouts before edits:

• explorer: map code truth, docs ownership, CI, and assets
• researcher: verify current external standards from primary sources
• worker: implement bounded fixes after controller verification
• tester: run validation commands and summarize failures
• reviewer: final read-only review against the run ledger

The controller verifies each report and records checkpoints in the ledger.

References

• _localsetup/tools/docs_alignment.py
• _localsetup/docs/_generated/docs-alignment-summary.md
• _localsetup/docs/OUTPUT_AND_DOC_GENERATION.md
• _localsetup/docs/DOCUMENT_LIFECYCLE_MANAGEMENT.md
• _localsetup/docs/WORKFLOW_STANDARD.md

Documentation Skill Refresh Note

Classification: route docs drift, generated artifact sync, and public documentation alignment here rather than creating a duplicate generic documentation skill.