docs-sync

name	docs-sync
description	Audit code-adjacent documentation for drift after behavior changes. Use this when runtime changes may have made READMEs, dashboard notes, API docs, or active architecture docs stale.
owner	any
trigger	null
version	1

Docs Sync

Use this after code changes when documentation accuracy matters.

What To Update

• User-facing README or workflow docs that now describe the wrong behavior
• Active architecture or integration docs that define current contracts
• Skill docs whose instructions no longer match platform behavior
• Dashboard/operator docs for changed control flows or task lifecycle behavior

What Not To Update Automatically

• Historical plans in docs/superpowers/plans/** unless the task explicitly asks for backfill
• Broad documentation sweeps without a concrete code change anchor
• Reference docs you have not verified against code

Workflow

1. Diff the code change first.
2. Identify which docs are source-of-truth for the changed behavior.
3. Prefer small, precise corrections over large rewrites.
4. If the drift surface is broad or ambiguous, report the stale docs before editing.
5. After edits, verify the updated wording still matches the code exactly.

Good Targets In This Repo

• README.md
• docs/** excluding historical plans unless requested
• .agents/skills/**/SKILL.md
• Dashboard/operator docs that explain task actions, recovery, or verification flows

Output Format

docs_sync:
  stale_docs:
    - path: "path/to/doc"
      problem: "what is stale"
      action: "updated|report-only"