| name | plan-docs-sync |
| description | Audit documentation against actual code behavior and plan corrections โ no rewrites in this pass. Drift taxonomy (stale, missing, phantom, contradictory, onboarding-breaking, inline rot, API-contract drift) with code-as-source-of-truth methodology. Onboarding-drift checks against .env.example and CLI --help; docs-as-code guardrails for same-PR updates. Docs describe real current behavior โ never aspirational or invented. 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".
|
| license | MIT |
Docs Drift Audit + Sync Plan
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.
โ Preservation Contract
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
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
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
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.
Required output (in order)
- Preservation-contract acknowledgment
- Drift taxonomy results (counts per type)
- Per-doc drift inventory (checklist)
- Burndown table (code-truth + risk)
- Sync + enhancement plan, phased
- Guardrails/tooling
- Research notes + citations
- Open questions /
[NEEDS VERIFICATION] list
Rules
- 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.
