Drydocs

drydocs — slim CLAUDE.md into a lean index

CLAUDE.md loads into context every session. When it's a monolith, every turn pays for detail it doesn't need. drydocs turns it into a lean index (identity + always-apply rules + pointers) and moves the bulk into a docs/ folder of atomic, linked notes.

It is non-destructive: it never touches your live CLAUDE.md. It writes the proposed lean version as dry-CLAUDE.md (one new file; your original stays put, and git keeps its history), and leaves the final mv dry-CLAUDE.md CLAUDE.md to you.

Quick start

H="${CLAUDE_SKILL_DIR}/scripts/slim_claude_md.py"   # the deterministic helper (stdlib-only)

python3 "$H" outline CLAUDE.md                       # 1. see sections + sizes (JSON)
# 2. classify each section (agent judgment) → KEEP vs EXTRACT + PARA bucket
python3 "$H" begin --apply                            # 3. make the dry-CLAUDE.md working copy
python3 "$H" refs --heading "<H>"                    #    find who references a block BEFORE moving it
python3 "$H" extract dry-CLAUDE.md --heading "<H>" --into docs/<bucket>/<note>.md --apply
# … repoint referrers (Edit), repeat per block …
python3 "$H" moc --root dry-CLAUDE.md --apply         # 4. (re)build the grouped link index
python3 "$H" finalize                                 # 5. report size drop + review/promote help (CLAUDE.md untouched)

Just run it end-to-end, don't stop to ask. The output is non-destructive: it never overwrites CLAUDE.md, it only produces fat-/dry- copies + notes as one git revert-able commit. So drive the whole flow with --apply and report the result when done. (The helper's --dry-run default is only for previewing a single command by hand.) The one thing you never do automatically is the final mv dry-CLAUDE.md CLAUDE.md promotion. That stays the user's call.

When it activates

Triggers: "slim/shrink my CLAUDE.md", "my CLAUDE.md is too long/huge", "organize CLAUDE.md into docs", "make CLAUDE.md a lean index / an MOC", "reduce CLAUDE.md tokens".

Guard — refuse unless inside a git work tree. git is the undo mechanism; the helper enforces this and refuses to run otherwise. Recommend working on a branch.

Organization model (summary)

Classification is grounded in three established methods — full detail + citations in references/organization-model.md:

• MOC (Maps of Content): CLAUDE.md becomes the root MOC — a lean hub of links + the few always-apply rules. Large areas get their own sub-MOC hub page.
• Zettelkasten: each extracted block becomes an atomic note (one topic), connected by links; "link, don't duplicate" resolves the case where a block already lives in an existing doc.
• PARA: the docs/ folders organize by actionability — projects/, areas/ (standards & rules), resources/ (reference & catalogs), archive/ (superseded).

If the repo already has a docs/ structure, respect it and map into the closest existing bucket; only lay down the PARA skeleton when creating docs/ fresh.

Flow

1. Analyze → classify. outline CLAUDE.md gives sized sections. For each, decide KEEP-in-root-MOC (identity, terse always-apply rules, the link index) vs EXTRACT (specs, catalogs, tool/setup detail, verbose prose, duplicates), and for EXTRACT pick the PARA bucket + note title. Rubric in references/classification.md. This step is read-only: keep the decision table + projected savings for your final summary, then continue straight into the next steps (no need to pause for approval).
2. Detect docs/ + choose targets. If absent, plan the PARA skeleton. If present, respect it and run dedup (references/dedup_merge.md): if an existing note already covers a block → plan a link to it (no new note); partial → append the delta; none → a new atomic note.
3. Per block: reference-scan → move → repoint (atomically). See references/extraction_pattern.md.
   • begin --apply once, to create the dry-CLAUDE.md working copy (never edit CLAUDE.md).
   • refs --heading "<H>" before moving: it tags referrers read/source, write-target, or incidental (heuristic — you refine). read/source → repoint to the note; write-target → decide: a block agents append to every session may be better kept inline (surface it); else repoint every referrer — never silently orphan one.
   • extract dry-CLAUDE.md --heading "<H>" --into docs/<bucket>/<note>.md [--mode new|append] moves the block to an atomic note and leaves a pointer stub that keeps the heading in the working copy. Split a multi-item catalog into several atomic notes (+ a hub) by extracting per sub-heading.
   • Apply the referrer repoints with Edit, then re-run refs to confirm nothing still says the content is "in CLAUDE.md".
4. Rebuild the index. moc --root dry-CLAUDE.md --apply regenerates the grouped link index (and any *.moc.md hub) from what's on disk. dry-CLAUDE.md is now: identity + always-apply rules + the grouped pointer index.
5. Finish + hand off. finalize reports the size drop and prints the review/promote instructions. Your original CLAUDE.md is left untouched; the only new file is dry-CLAUDE.md (plus the notes). Do not promote for the user (the final mv dry-CLAUDE.md CLAUDE.md is theirs). Commit the change as one commit so git revert is a clean undo.

Safety & idempotency

• Non-destructive: the helper never creates or overwrites a file named CLAUDE.md. Promotion is the user's manual mv dry-CLAUDE.md CLAUDE.md.
• Act, don't ask: the output is non-destructive and git-reversible, so run the whole flow with --apply without pausing for permission. Report what you did at the end. The only never-automatic step is the final mv dry-CLAUDE.md CLAUDE.md promotion.
• Idempotent: re-running skips blocks already turned into pointer stubs and rows already indexed; a second pass on a slim repo is a no-op.
• Reversible: every change is a git-visible edit; the operation is one commit, so git revert undoes it (removes dry-CLAUDE.md and the notes). Your CLAUDE.md was never modified in the first place.
• Scope: only touches Markdown / agent-instruction files. Never edits application source or config. No RAG / embeddings / vector index — navigation is the manifest + grep + links.

References

• references/organization-model.md — MOC + PARA + Zettelkasten, with citations. The backbone.
• references/classification.md — the KEEP-vs-EXTRACT rubric and which PARA bucket.
• references/extraction_pattern.md — the reference-scan → move → repoint discipline (the hard part).
• references/dedup_merge.md — detecting when to link to an existing note instead of creating one.
• scripts/slim_claude_md.py — the deterministic helper (outline, refs, extract, moc, begin, finalize, stamp). --help on any subcommand.