plan-docs-sync · diff
git:20260923.cf348bd to git:20260923.68c095e
4 added, 4 removed. Audit A to A.
---
name: plan-docs-sync
description: >
- Audit documentation against actual code behavior and plan corrections — no rewrites in
- this pass. Use when asked to "docs drift", "sync docs with code", "audit documentation",
- "stale README", "onboarding docs broken", "doc sync plan", "phantom docs", or "docs out
- of date". Why-we-chose-X / ADRs → docs-adr.
+ 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.