doc-sync-sweep
Skill8 starsChanged 11 days agoApache-2.0View on GitHub
Audit documentation surfaces for drift against recent code commits. Use after substantive code-shipping commits (feat/fix/refactor), at end-of-session sign-off, or when PM asks "are docs in sync?". Catches the "living documentation describing dead code" pattern before it accumulates.
In this repository39 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- .cursor/rules/architecture-patterns.mdcCursor rule
- .cursor/rules/completion-discipline.mdCursor rule
- .cursor/rules/github-tracking.mdcCursor rule
- .cursor/rules/programmer-briefing.mdcCursor rule
- .cursor/rules/verification-first.mdcCursor rule
- ab-a-isolationSkill
- assign-sprint-safelySkill
- audit-cascadeSkill
- brief-coding-agentSkill
- check-mailboxSkill
- cleanup-dev-activeSkill
- close-issue-properlySkill
- cohort-attention-rollupSkill
- compost-reviewSkill
- continue-narrativeSkill
- create-omnibusSkill
- create-session-logSkill
- cut-releaseSkill
- delete-module-safelySkill
- deliver-mailSkill
- discovered-work-captureSkill
- draft-blog-postSkill
- draft-weekly-shipSkill
- duty-cycle-tickSkill
- narrative-verificationSkill
- piper-draft-issueSkill
- piper-draft-specSkill
- piper-sprint-planSkill
- piper-stakeholder-updateSkill
- piper-synthesize-feedbackSkill
- propose-featureSkill
- publish-to-blogSkill
- query-github-boardSkill
- template-auditSkill
- trust-checkSkill
- update-calendarSkill
- update-current-stateSkill
- update-piperSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 3 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 102
If 0 drift found, report "Sweep clean" — that's a valuable positive signal for the discipline.
- Distinctive: line 126
Should it have a tooling component (hook that suggests doc files to audit based on commit diff)?
- Distinctive: line 129
Should the historical-context distinction become its own micro-pattern (verb tense as the discipline marker — past-tense for deletions, …
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
doc-sync-sweep
Catch documentation drift before it accumulates. After code changes, documentation surfaces that reference the old code shape become assertions of behavior the code doesn't honor — a Pattern-064-adjacent shape ("living documentation describing dead code"). The skill makes the drift-check explicit and routine.
Origin
Filed 2026-05-16 in response to three independent instances in ≤48 hours of doc-vs-code drift:
- Methodology-core docs (Friday):
MULTI_AGENT_INTEGRATION_GUIDE.md+HOW_TO_USE_MULTI_AGENT.mdreferencedservices/orchestration/engine.pyafter #1094 deleted it. New agents following the guide would have hit ImportError. Fixed via banner-not-rewrite. ⚠️ Correction (2026-09-01, found during the B3 architectural-review corpus pass): that May-15 banner-not-rewrite fix itself went stale — it assertedMultiAgentCoordinator"survives," which became false when #1436 deleted the entireservices/orchestration/island on 2026-07-18. Both files carried a false "survives" claim for six weeks before B3 caught it. The lesson generalizes: banner-not-rewrite is a point-in-time fix, not a durable one — a banner that asserts "X still works" needs the same drift-check discipline this skill exists to provide, or it becomes exactly the "living documentation describing dead code" failure this skill was filed to catch, one level removed. Both banners corrected same-day; see the files' own git history for the worked example of re-doing a stale banner. - Repository docstring (Saturday AM):
StandupConversationRepository.add()docstring asserted"AsyncSessionFactory.session_scope() handles commit"— butsession_scope()does NOT commit. The assertion shaped my mental model on initial audit; the drift was the bug surface (caught via #1079 fix when I switched totransaction_scope()). - Templated user-facing copy (Saturday PM): hard-coded canned responses asserted product behavior the code didn't honor — "run the setup wizard" (no setup wizard exists; #1065 fixed); "All open PRs are less than 7 days old" (handler only checked 100 most recent items; not "all"). Surfaced via #1064 investigation.
CIO Saturday-AM tracker noted "12w" as a watch surface needing one more instance to trigger sub-pattern decision. By Saturday PM, three instances had landed. The recurring shape is structural, not incidental.
When to use
- After any substantive code-shipping commit (
feat:/fix:/refactor:per Conventional Commits): run a focused sweep on doc surfaces likely affected - At end-of-session sign-off: 48-hour sweep before ending the session, catching drift that accumulated across multiple commits
- When PM asks: "are the docs current?" or "did anything else drift?"
- When you notice an assertion in a doc/docstring/comment that you can't immediately verify the code still honors
When NOT to use
- For doc-only commits (
docs:/log:/mail:) — no code change, no drift risk - For trivial commits (whitespace, comment-only) — unless the comment was an assertion
- During time-sensitive incident response — defer until the immediate fix lands
Procedure
Step 1: Identify the change surface
# After a single commit
git show HEAD --stat
git show HEAD --name-only
# Or: 48-hour sweep
git log --since="2 days ago" --author="$(git config user.email)" --oneline | grep -E "^[a-f0-9]+ (feat|fix|refactor)"For each commit, note:
- Files modified, added, deleted
- Class names / function names that changed signature, were renamed, or deleted
- New patterns / ADRs introduced
- Behavior changes (especially: empty-state branches, error paths, defaults)
Step 2: Map to likely doc surfaces
For each change kind, the likely-affected doc surface(s):
| Change | Doc surfaces to check |
| Class/function deleted | grep -rn "<name>" services/ web/ --include="*.py" for remaining docstring/comment references; same on docs/ |
| Class/function renamed | Same as above; also check ADR/Pattern bodies that name the symbol |
| API signature changed | docs/internal/architecture/current/api-*.md; route conventions doc; CLAUDE.md API Conventions section |
| New pattern landed | docs/internal/architecture/patterns/README.md entry + the pattern body itself |
| New ADR landed | ADR catalog README; cross-references from other ADRs |
| Behavior change in empty-state branch | Templated canned-response strings in the same module (per #1064 investigation finding) |
| Test deletions | Co-located tests in services/<module>/tests/ (often missed in repo-level tests/ cleanup) |
| Architectural refactor | docs/briefing/BRIEFING-ESSENTIAL-ARCHITECT.md tech-debt list |
| Sprint milestone change | docs/briefing/BRIEFING-CURRENT-STATE.md |
Step 3: Audit each surface
For each doc surface identified, read it and check whether its assertions still match the code. Three questions:
- Does the doc name code that no longer exists? (deleted class/file/function)
- Does the doc describe behavior the code no longer produces? (deleted/renamed code paths)
- Does the doc assert a contract that the code doesn't honor? (the most insidious — requires reading the docstring AND the code it claims to describe)
Question 3 is the load-bearing one. Question 1 + 2 are usually obvious. Question 3 is what the 12w pattern names: the doc is structurally correct (references exist) but semantically wrong (the contract it asserts isn't what the code does).
Step 4: Disposition each finding
For each drift instance:
- Trivial (5 min or less): fix in place during the sweep
- Larger (more than 5 min, or requires design decision): file as discovered work via the
discovered-work-captureskill; tag withdoc-driftif such a label exists - Historical context worth preserving: rewrite as past-tense ("the prior X was deleted in #1094" instead of "X handles commit") — explicit historical narration is correct, drift-claiming-current-behavior is wrong
Step 5: Report
Brief report (3-5 bullets max):
- N drift instances found
- M fixed in place
- N-M filed as discovered work (link to issues)
- Any patterns observed (e.g., "all drift was in module X" — methodology signal)
If 0 drift found, report "Sweep clean" — that's a valuable positive signal for the discipline.
Anti-patterns
| Anti-pattern | Why it's bad |
| Sweep only at session end | Drift accumulates within the session; catching it after one commit is much cheaper than after 19 |
| Sweep only the docs you remember | The 12w pattern surfaces in docs you DIDN'T remember; the systematic mapping in Step 2 is the value |
| Fix all drift in place | Some drift is structural (e.g., methodology-core engine guides post-#1094) and warrants a deliberate banner-vs-rewrite decision, not an inline patch |
| Skip the historical-context distinction | Confusing "X was deleted" (correct narration) with "X handles commit" (drifted assertion) blurs the discipline |
| Treat as Lead Dev only | This is cross-role: any agent shipping code can drift docs |
Connection to other patterns/skills
- Pattern-064 (Alive Scaffolding): 12w is the documentation-layer variant. Same shape, different surface.
- Pattern-046 (Completion Discipline): same family — "shipped but not finished" applied to docs.
close-issue-properlyskill: end-of-issue discipline; this skill is end-of-commit discipline. Both close-the-loop.discovered-work-captureskill: chained dependency — larger drift findings go through capture-as-issue.
Future formalization
This is a v0.1 draft. Open questions for CIO methodology review:
- Is this its own skill, or a clause within
close-issue-properly/ sign-off discipline? - Should it have a tooling component (hook that suggests doc files to audit based on commit diff)?
- How does it interact with the existing
update-current-stateskill (which is briefing-focused but adjacent)? - Naming:
doc-sync-sweepvsdocumentation-drift-checkvs other? - Should the historical-context distinction become its own micro-pattern (verb tense as the discipline marker — past-tense for deletions, present-tense for current behavior)?
PM ratification + CIO methodology review pending. This skill is DRAFT — propose for review until ratified.
Cross-references
- CIO 12w watch surface (Saturday AM bundled acks, 2026-05-16)
- Lead Dev second-instance memo (
mailboxes/cio/read/archive/2026-Q2/memo-lead-to-cio-cc-arch-ceo-12w-second-instance-living-docs-describing-dead-code-2026-05-16.md— moved frominbox/toread/since this citation was written, then quarterly-archived; path corrected 2026-10-08) - #1064 investigation memo (
dev/2026/05/16/floor-fabrication-investigation.md) — third instance surfacing - Pattern-064 (Alive Scaffolding) + Pattern-064 Evolution section (the broader family this fits)
- #1079 fix (
b5d7972d) — concrete instance of docstring drift inrepositories.py:2335-2337 - methodology-core engine-drift fix (
19b33a89, Friday) — concrete instance of guide-doc drift
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

