readme-sync

Purpose

Project onboarding docs (typically an intro series under docs/, a main README.md index, or a wiki) lose all value once they drift from the code. The sole responsibility of this skill is to eliminate staleness — not to rewrite, not to polish wording, not to add new content.

The governing principle is that code is the single source of truth. Any description in the docs that disagrees with the code is a bug, and the fix is to correct the doc rather than bend it toward the old description.

When to use

• After completing a feature, a refactor, or a bug fix and archiving it (code moved; docs may be stale)
• After replacing a Stub with a real implementation
• After a refactor that renamed packages, moved files, or changed signatures
• During a periodic health check (e.g., monthly)
• When the user says things like "update the docs" / "is the doc out of date?" / "sync docs after this code change"

When NOT to use

• Writing new docs from scratch — use guide-and-manual instead
• Reviewing the quality of code changes themselves — use code-review
• Distilling freshly completed work into knowledge — use change-recap (this skill does not produce new knowledge; it only removes staleness)
• Fixing bugs — use error-handling (but after the fix changes the code, call this skill to sync the docs)

Non-negotiable constraints

1. Treat code as the source of truth. Every decision to change or keep a passage must be based on code actually read in this session. Do not reach conclusions from memory or from the old doc — memory and stale text are exactly what produced the drift in the first place.
2. Make minimal changes. Fix only what is outdated or wrong; leave already-correct content untouched. Do not take the opportunity to rewrite, "incidentally optimize" wording, or restructure. Passages that are correct but averagely written stay as-is — opportunistic rewrites are how scope creeps in.
3. Get user confirmation at every stage. The three gates — drift list, update plan, and write-to-disk — each require explicit user agreement before proceeding. Writing silently breaks trust and makes the user unable to catch scope creep.
4. Preserve user-added content. Manual notes, examples, and gotchas that a human added to the docs should be kept unless the user explicitly asks to remove them.
5. Diagrams must render. After any change to a Mermaid / PlantUML / graphviz diagram, verify the syntax pairing (@startuml/@enduml, complete mermaid code fence, etc.). A broken diagram is worse than a stale paragraph because it actively fails to render.
6. Match the doc's existing quality bar (applies only to newly added content; do not use this as a pretext to rewrite existing content). Follow the language, target audience, and level of detail the doc already uses.

Doc inventory (what gets maintained)

This skill does not assume a fixed directory layout. The very first step in Stage 0 is to confirm with the user: which docs are being maintained this run?

Common layouts (any combination is valid):

• Per-chapter files under docs/ (e.g., 01-overview.md / 02-architecture.md / ...)
• A single README.md plus sub-files under docs/
• A wiki/ directory
• CONTRIBUTING.md + docs/getting-started.md

Process

Stage 0: Confirm the maintenance scope

Confirm with the user:

1. Targets: Which docs are scanned this run? (list of paths)
2. Granularity:
   • Full scan: compare each doc against the code one-by-one (the default for first runs or after long gaps)
   • Targeted update: the user narrows the scope (e.g., "only the routing part", "only the auth flow", "I just changed module X")

If the user does not specify, default to a full scan but let them narrow it.

Stage 1: Drift scan (code ↔ docs) ★ core

Do not skip this stage and jump straight into editing. The reasoning is straightforward: drift cannot be fixed without first knowing exactly where the code currently stands, and any edit made before that knowledge is in hand is just a guess.

1.1 Establish the current state of the code (use tools, not memory)

Sample the code along the following dimensions and record the actual values (adapt the concrete commands to the language/framework):

Efficient approach: for the "read every file" pass, dispatch Agent(Explore) in parallel split by module — it is both faster and more complete. However, the conclusions must be re-verified line-by-line back in the main thread, because an Explore summary can silently drop nuance.

1.2 Compare each doc against the code and produce the drift list

For each doc, check its factual claims against the current code one by one. Focus on these high-frequency drift zones:

1.3 Output the drift list (wait for user confirmation)

Output the table below and wait for the user to check off each item. The user may: fix all / fix some / skip / add items.

• "Suggested action" should be brief — "fix / add / remove node X from diagram / add section Y" — without spelling out the concrete wording (that is Stage 2's job).
• If a doc has no drift at all, mark it explicitly as "✅ no staleness" rather than padding the list.

Submit the list and wait for the user to confirm which items to fix.

Stage 2: Propose the concrete update plan

For each confirmed drift item, give a file-and-section-precise old→new:

• Fix: paste the doc's original sentence (old) → the corrected sentence (new), and state why, citing file:line from the code.
• Add: state which doc and after which section to insert, and provide a draft of the new paragraph / table / diagram.
• Delete: state which paragraph or diagram to remove, and why leaving it in would mislead.
• Diagram: if a Mermaid / PlantUML diagram's content is stale (e.g., nodes added/removed in a class diagram, steps changed in a sequence diagram), provide a full rewrite of the block.

Principle re-check (self-audit again to prevent scope creep):

• Does every change map directly to a Stage-1 drift item? Drop any change that does not.
• Did you touch a passage that is "correct but averagely worded"? If so, revert it.
• Does any newly added content meet the "quality bar" (matching the doc's existing language, audience, and level of detail)?

Submit the plan and wait for the user to confirm it (item-by-item or wholesale) before writing.

Stage 3: Apply the updates + diagram validation

Use Edit / Write to commit the user-approved plan to disk. Immediately self-check after writing:

1. Diagram health:
   • Code fences are properly paired (@startuml / @enduml, mermaid ```mermaid closing, etc.)
   • No syntax breakage
   • For any diagram that was touched, render it mentally or with a tool to confirm the structure is correct
2. Cross-references: file names / links in the main index still point to docs that exist; inter-doc references like "see [N]" still resolve.
3. Scope audit: run git diff <docs-path> on the actually changed lines and confirm nothing outside the approved plan slipped in.

If a self-check surfaces an issue, fix it before continuing.

Stage 4: Consistency verification + summary

4.1 Spot re-verification

Randomly sample 3–5 factual claims from this run's changes and re-read the code on the spot to confirm "what the doc now says == what the code now does". If any one fails to match, go back to Stage 2 and patch.

4.2 Summary output

## Doc Update Summary

**Scan scope**: <list of maintained docs / full or targeted: xxx>
**Code sampling**: <which key files were read / how many Explore agents used>

**Total drift items**: N (structure drift x / signature drift y / Stub-implemented z / ...)

**Updated**:
- <doc path>: <what was changed, mapping to which drift item>
- ...

**Skipped / rejected by user**: <list them, for the record>

**Known TODOs / placeholders still present** (the doc already labels them honestly — these are not staleness):
- <e.g., module X is still a Stub; config item Y is a placeholder pending decision>

**Diagram validation**: ✅ all paired, no syntax breakage
**Spot re-verification**: ✅ x/y items verified consistent

Boundaries with other skills

• code-review: reviews the quality of git-changed code itself. This skill updates docs.
• change-recap: distills freshly completed work into knowledge. This skill removes doc staleness and does not produce new knowledge — but if the scan turns up "a new feature the doc does not yet cover", suggest the user run change-recap to capture it; this skill does not do that on its own.
• error-handling: handles bugs. After a bug fix changes the code, call this skill to sync the docs.