---

name: plan-docs-sync description: > Plan-only audit of documentation against actual code behavior. Use when "docs drift", "sync docs with code", "audit documentation", "stale README", "onboarding docs broken", "phantom docs", or "docs out of date". Decisions/ADRs → docs-adr. license: MIT effort: high

Docs Drift Audit + Sync Plan

Degree of freedom: MIXED — inventory globs are exact; drift judgment is high. Stay plan-only. No rewrites until approved.

Role: Senior engineer + technical writer.

Task: Audit all documentation against what the code actually does, find every drift, plan corrections. README, CONTRIBUTING, setup/onboarding, API docs, JSDoc/docstrings, architecture notes, .env.example, CLI --help, changelogs. Audit & plan only.

This skill vs neighbors

Skill	Does
plan-docs-sync (this)	Plan doc corrections from code truth
docs-writer	Write/improve docs (execution)
workflow-housekeep	README refresh as part of housekeeping
plan-stub-checker	Stubs/dead UI — often surfaces phantom docs

Loop position: run last in the six-skill plan loop. See docs/PLAN-LOOPS.md.

How to reason (every plan item)

1. Propose — correction that makes the doc match code truth
2. Risk — onboard fail, phantom API, or invented behavior if left stale
3. Keep-working — claims already backed by path:line
4. Phase — factual drift first; wording last (do not execute)

Worked example

Propose: drop STRIPE_WEBHOOK_SECRET from the README setup list (absent from .env.example and code); document POST /v1/webhooks/stripe which exists undocumented. Risk: onboarding fails on a phantom env var; integrators miss a live endpoint. Keep-working: CONTRIBUTING install steps match package.json scripts. Phase: first sync slice — factual drift only.

---

⛔ Preservation Contract [LOW freedom — run exactly]

Read references/preservation-contract.md. Acknowledge in output #1.

Core guardrail: docs describe real, current behavior — never aspirational or invented.

---

References

File	Contents
references/drift-taxonomy.md	Types, detection passes, guardrails
references/output-templates.md	Burndown, phased sync plan

---

Phase flow

1. Inventory all doc surfaces
2. Code-as-source-of-truth pass
3. Reverse pass (missing docs)
4. Onboarding replay (.env.example + CLI help)
5. Signature + cross-doc consistency + links
6. Burndown + phased sync plan
7. Research + guardrails (docs-as-code, CI drift checks)

---

Phase 1 — Doc inventory [LOW freedom — run exactly]

Glob: README.md CONTRIBUTING.md docs/**/*.md **/*README*.md
Glob: .env.example

List: README, CONTRIBUTING, docs/, inline JSDoc targets, OpenAPI, CLI help, changelog.

---

Phase 2–5 — Detection [HIGH freedom]

Execute all passes in references/drift-taxonomy.md.

Onboarding-drift check (standout): extract env var names + setup commands from onboarding docs; diff against .env.example keys and package.json scripts; run CLI --help where safe and compare.

Every drift: doc claim + code truth (path:line). Can't verify → [NEEDS VERIFICATION].

---

Phase 6 — Burndown + sync plan [HIGH freedom — plan only]

Template: references/output-templates.md

Quantify: e.g. "9 phantom env vars, 14 undocumented endpoints, 6 onboarding steps that fail".

Per drift: before/after correction + "what's still accurate here". Plan only — no rewrites until approval.

Industry enhancements (Firecrawl, current year): docs-as-code, doc-in-same-PR, CI drift vs .env.example + CLI help, generated API refs, llms.txt.

Self-critique before the burndown [LOW freedom — do not skip]

1. evidenced-not-assumed — every drift is doc claim + code path:line (or [NEEDS VERIFICATION])
2. plan-only — no rewrites; deletions are proposals
3. phase justified — factual drift before wording polish
4. right-owner — why-we-chose-X → docs-adr; stubs/dead UI → plan-stub-checker
5. no-false-safety — never document invented or aspirational behavior

---

Required output (in order)

1. Preservation-contract acknowledgment
2. Drift taxonomy results (counts per type)
3. Per-doc drift inventory (checklist)
4. Burndown table (code-truth + risk)
5. Sync + enhancement plan, phased
6. Guardrails/tooling
7. Research notes + citations
8. Open questions / [NEEDS VERIFICATION] list

End the turn with a standalone recap in chat: the two or three highest-impact drifts and the first sync slice to approve. The report is the deliverable — write it before the recap.

---

Rules [LOW freedom — run exactly]

• Plan only — do not rewrite docs until approved.
• Code is source of truth. Every drift = doc claim + code fact.
• Never document invented or aspirational behavior.
• Stale docs get corrected, not deleted. Deletions are proposals.
• Separate factual drift vs subjective wording improvement.