docs-alignment-maintainer
npx machina-cli add skill gaelic-ghost/productivity-skills/docs-alignment-maintainer --openclawDocs Alignment Maintainer
Run a deterministic two-pass docs alignment workflow across repositories under a provided workspace root. Detect drift first, then apply only bounded high-confidence fixes when requested.
Inputs
Pass runtime inputs from the calling prompt:
--workspace <path>--exclude <path>(repeatable)- Optional
--exclude-file <path>with one path per line
Defaults are intentionally not hardcoded in the skill body so automation can control scope per run.
Workflow
- Run pass 1 discovery and checks with
scripts/docs_alignment_maintainer.py. - Review unaligned repos and issue categories.
- If safe remediation is desired, run pass 2 with
--apply-fixes. - Re-check touched repos (handled by the script) and inspect remaining issues.
- Report results from Markdown and JSON outputs.
Commands
Audit only:
python3 scripts/docs_alignment_maintainer.py \
--workspace ~/Workspace \
--exclude ~/Workspace/services \
--print-md \
--print-json
Audit and safe fixes:
python3 scripts/docs_alignment_maintainer.py \
--workspace ~/Workspace \
--exclude ~/Workspace/services \
--apply-fixes \
--md-out /tmp/docs-alignment-report.md \
--json-out /tmp/docs-alignment-report.json
Fail the run when unresolved issues remain:
python3 scripts/docs_alignment_maintainer.py \
--workspace ~/Workspace \
--exclude ~/Workspace/services \
--apply-fixes \
--fail-on-issues
Safety Rules
- Never commit changes automatically.
- Edit docs only (for example
README.md,CONTRIBUTING.md,ROADMAP.md,docs/*.md). AGENTS.mdis out-of-scope for this skill and is owned by a dedicated AGENTS maintainer workflow.- Never edit source code, lockfiles, or manifests.
- Apply only bounded replacements and concise quickstart insertion when evidence is explicit.
- Keep diffs minimal and preserve existing formatting style.
Output Contract
The script emits:
- Markdown summary with run context, discovery summary, unaligned repos, fixes applied, remaining issues, modified files, and errors.
- JSON report containing:
run_contextrepos_scannedunaligned_reposfixes_appliedpost_fix_statuserrors
Use JSON for automation pipelines and Markdown for operator review.
Automation Templates
Use $docs-alignment-maintainer inside automation prompts so Codex reliably loads this skill context.
For ready-to-fill Codex App and Codex CLI (codex exec) templates, including guardrails, placeholders, and customization knobs, use:
references/automation-prompts.md
References
- Common checks and discovery rules:
references/checks-common.md - Swift guidance:
references/checks-swift.md - JS/TS guidance:
references/checks-js-ts.md - Python guidance:
references/checks-python.md - Rust guidance:
references/checks-rust.md - Safe-fix policy boundaries:
references/fix-policies.md - Report schema and section contract:
references/output-contract.md - Automation prompt templates:
references/automation-prompts.md
Source
git clone https://github.com/gaelic-ghost/productivity-skills/blob/main/docs-alignment-maintainer/SKILL.mdView on GitHub Overview
Docs Alignment Maintainer runs a deterministic two-pass workflow to detect documentation drift across repositories within a workspace and fix only bounded, high-confidence issues. It audits Markdown docs against manifests and tooling, then produces both a Markdown and JSON alignment report to support automation and human review. Language-aware checks cover Swift, JavaScript/TypeScript, Python, and Rust to keep multi-language docs consistent.
How This Skill Works
The tool runs pass 1 discovery with scripts/docs_alignment_maintainer.py to identify drift and categorize issues. Review the results, then, if safe remediation is desired, run pass 2 with --apply-fixes and re-check touched repos. It outputs a Markdown summary and a JSON report, including run_context, repos_scanned, unaligned_repos, fixes_applied, post_fix_status, and errors.
When to Use It
- Run as part of scheduled automation for repo hygiene to keep docs in sync across a workspace.
- When docs drift after changes to manifests or tooling across repositories.
- When you need a Markdown + JSON alignment report for operator reviews or audits.
- When maintaining documentation across Swift, JavaScript/TypeScript, Python, and Rust code bases.
- When you want bounded, high-confidence fixes applied only after an audit.
Quick Start
- Step 1: Audit only — python3 scripts/docs_alignment_maintainer.py --workspace ~/Workspace --exclude ~/Workspace/services --print-md --print-json
- Step 2: Audit + safe fixes (if issues exist) — python3 scripts/docs_alignment_maintainer.py --workspace ~/Workspace --exclude ~/Workspace/services --apply-fixes --md-out /tmp/docs-alignment-report.md --json-out /tmp/docs-alignment-report.json
- Step 3: Re-check and inspect — re-run the tool to validate touched repos and review the Markdown/JSON reports; optionally fail on issues with --fail-on-issues
Best Practices
- Always start with an audit pass (no changes) before attempting fixes.
- Use --print-md and --print-json to capture both human-readable and machine-readable outputs.
- Limit scope with --exclude or --exclude-file to reduce noise from non-doc directories.
- Review unaligned_repos and issue categories thoroughly before enabling --apply-fixes.
- Keep changes minimal and contain edits to Markdown docs only; never touch code, lockfiles, or manifests.
Example Use Cases
- Regularly run across a Python project and its JS/TS dependencies to keep docs aligned with evolving APIs.
- After a major library upgrade, align docs across multiple repos so references match new behavior.
- Schedule monthly drift checks to generate Markdown + JSON reports for stakeholder reviews.
- Coordinate Swift and Rust documentation alignment across libraries and apps in a polyglot codebase.
- Run an audit-only pass to verify alignment and generate a report without applying changes.
