Agent-Skills.md

Agent Skills: Sync docs

Detect docs-vs-code drift from a diff. Use when the user says "sync docs" or "update changelog".

UncategorizedID: OutlineDriven/odin-claude-plugin/sync-docs

Repository

OutlineDriven/odin-claude-plugin
OutlineDrivenLicense: Apache-2.0
32

Install this agent skill to your local

pnpm dlx add-skill https://github.com/OutlineDriven/odin-claude-plugin/tree/HEAD/plugins/odin-create/skills/sync-docs

Skill Files

Browse the full folder contents for sync-docs.

Download Skill

Loading file tree…

plugins/odin-create/skills/sync-docs/SKILL.md

Skill Metadata

Name
sync-docs
Description
'Use when a behavioral diff may have left docs or CHANGELOG stale. Detects docs-vs-code drift and applies only safe fixes. Also handles stale code comments when tidy targets them. Not for roadmap drift — use drift-detect. Don''t use for remote or irreversible changes.'

Sync docs

Contract

| Field | Bound contract | |---|---| | Trigger | User says 'sync docs' or 'update changelog' after a behavioral change. | | Authority | Reversible local writes only. Edit named local doc files and write a fix ledger. Rollback reverts the edited files to their pre-edit content. | | Side effect | Applies only safe fixes (version bump plus CHANGELOG Unreleased entry) and writes a fix ledger with before/after evidence. | | Done | Safe fixes are applied or explicitly unavailable, and all residual drift is flagged with file:line evidence and reasons. |

Inputs

  • Mode: report (default) or apply. apply still edits only safe-fix issues.
  • Scope: recent (changed files from current branch or last few commits), before-pr (branch diff against PR base), or all (all tracked code and docs).
  • Base: explicit base ref preferred. If absent, resolve the default branch, then fall back to HEAD~5 for recent.

Refusal

  • No diff or empty scope: stop. Report the resolved base and scope; do not fabricate drift.
  • Ambiguous base ref: stop. List candidate refs and ask the user.
  • Manifest parse failure: skip the version-bump safe fix for that manifest; flag the file as MEDIUM with reason.
  • Post-edit read mismatch: revert the edit; reclassify the issue as flag-only with reasonFlagOnly.
  • Codegraph unavailable: use syntax fallback; downgrade confidence to MEDIUM for symbol-dependent claims.

Procedure

  1. Pick scope and base. Refuse ambiguous review scope when the user expects PR readiness. Resolve the base ref and compute the changed-file list. In ODIN tool mode, use bash only for git commands; use find, search, read, lsp, ast_grep, and edit for everything else. Done when: the scope and base are resolved and the changed-file list is computed.
  2. Compute changed code. Keep only source/config/package files that can change docs. Exclude pure docs, vendored/generated paths, lockfiles unless version docs mention package manager output, and deleted files that were never public. Done when: the changed-code file list is filtered.
  3. Extract coupling terms. For each changed code file derive filename stem, full path, import strings from the diff, and exported/public symbols via codegraph when indexed or syntax fallback. Load references/doc-issues.md for the full detection recipe. Done when: coupling terms are extracted for every changed file.
  4. Discover related docs. Search live doc surfaces: README.md, CHANGELOG.md, docs/**/*.md, *.md at repo root. For each coupling term, search docs and record doc, line, term, referenceType. Done when: every coupling term is searched against docs.
  5. Classify issues. Load references/doc-issues.md for the severity taxonomy, safe-fix boundary, and default ignore list. Classify each finding as HIGH, MEDIUM, or LOW. Ignore generated docs unless explicitly in scope, vendored docs, changelog append-only entries, and versioned snapshots unless in scope. Done when: every finding is classified with severity and safe-fix eligibility.
  6. Apply safe fixes only (in apply mode). Safe fixes are: version bump (replace stale semver in docs with the manifest version when the line clearly labels a version) and CHANGELOG ## [Unreleased] entry (insert a minimal bullet citing commit/file evidence). Load references/detection-recipes.md for per-ecosystem manifest version fields and changelog evidence commands. Do not auto-edit removed exports, import paths, examples, undocumented exports, dead-code docs, or doc-drift prose. Those require human intent. Done when: safe fixes are applied or confirmed unavailable.
  7. Flag the rest. Emit a compact report sorted by severity then file path. Done when: every non-safe-fix finding is flagged with file:line evidence and reason.
  8. Return fix ledger. For every edit record file, line, type, before, after, and evidence source. For every flag-only item record reasonFlagOnly. Done when: the fix ledger is complete.

Failure modes

  • Partial results: if some coupling terms resolve and others do not, report resolved issues and flag unresolved terms. Never widen scope to compensate for missing evidence.
  • Rollback: revert any edited file to its pre-edit content. The fix ledger records before/after for every edit.

Output

A JSON fix ledger: opCell, scope, base, changedCode array, relatedDocs array, fixesApplied array, flagged array. Completion means safe fixes are applied or explicitly unavailable, and all remaining drift is flagged. A clean report with no edits is valid only after the diff-to-doc mapping and taxonomy pass ran.