agentleFS
mediajunkiemediajunkie/piper-morgan-product/.claude/skills/doc-sync-sweep/SKILL.md

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.

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
  1. Distinctive:

    If 0 drift found, report "Sweep clean" — that's a valuable positive signal for the discipline.

    line 102
  2. Distinctive:

    Should it have a tooling component (hook that suggests doc files to audit based on commit diff)?

    line 126
  3. Distinctive:

    Should the historical-context distinction become its own micro-pattern (verb tense as the discipline marker — past-tense for deletions, …

    line 129

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:

  1. Methodology-core docs (Friday): MULTI_AGENT_INTEGRATION_GUIDE.md + HOW_TO_USE_MULTI_AGENT.md referenced services/orchestration/engine.py after #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 asserted MultiAgentCoordinator "survives," which became false when #1436 deleted the entire services/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.
  2. Repository docstring (Saturday AM): StandupConversationRepository.add() docstring asserted "AsyncSessionFactory.session_scope() handles commit" — but session_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 to transaction_scope()).
  3. 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):

ChangeDoc surfaces to check
Class/function deletedgrep -rn "<name>" services/ web/ --include="*.py" for remaining docstring/comment references; same on docs/
Class/function renamedSame as above; also check ADR/Pattern bodies that name the symbol
API signature changeddocs/internal/architecture/current/api-*.md; route conventions doc; CLAUDE.md API Conventions section
New pattern landeddocs/internal/architecture/patterns/README.md entry + the pattern body itself
New ADR landedADR catalog README; cross-references from other ADRs
Behavior change in empty-state branchTemplated canned-response strings in the same module (per #1064 investigation finding)
Test deletionsCo-located tests in services/<module>/tests/ (often missed in repo-level tests/ cleanup)
Architectural refactordocs/briefing/BRIEFING-ESSENTIAL-ARCHITECT.md tech-debt list
Sprint milestone changedocs/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:

  1. Does the doc name code that no longer exists? (deleted class/file/function)
  2. Does the doc describe behavior the code no longer produces? (deleted/renamed code paths)
  3. 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-capture skill; tag with doc-drift if 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-patternWhy it's bad
Sweep only at session endDrift accumulates within the session; catching it after one commit is much cheaper than after 19
Sweep only the docs you rememberThe 12w pattern surfaces in docs you DIDN'T remember; the systematic mapping in Step 2 is the value
Fix all drift in placeSome 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 distinctionConfusing "X was deleted" (correct narration) with "X handles commit" (drifted assertion) blurs the discipline
Treat as Lead Dev onlyThis 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-properly skill: end-of-issue discipline; this skill is end-of-commit discipline. Both close-the-loop.
  • discovered-work-capture skill: chained dependency — larger drift findings go through capture-as-issue.

Future formalization

This is a v0.1 draft. Open questions for CIO methodology review:

  1. Is this its own skill, or a clause within close-issue-properly / sign-off discipline?
  2. Should it have a tooling component (hook that suggests doc files to audit based on commit diff)?
  3. How does it interact with the existing update-current-state skill (which is briefing-focused but adjacent)?
  4. Naming: doc-sync-sweep vs documentation-drift-check vs other?
  5. 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 from inbox/ to read/ 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 in repositories.py:2335-2337
  • methodology-core engine-drift fix (19b33a89, Friday) — concrete instance of guide-doc drift

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.