update-codemaps

update-codemaps

Regenerate architecture diagrams. Detects what changed; redraws what needs redrawing.

Method

1. Locate codemaps. Mermaid sources, ASCII trees, or external (e.g. Excalidraw / draw.io files).
2. Detect drift since last generation:
   • New top-level files/dirs
   • Removed files/dirs
   • Significant LOC changes (>30%) in mapped components
   • New external deps
3. Redraw incrementally. Don't regenerate everything — only the affected diagrams.
4. Verify — does the new diagram match current code? Spot-check 3 nodes.
5. Commit with a clear message: "docs: refresh codemap (added X, removed Y, restructured Z)".

Output shape

Diagrams found:
  - ARCHITECTURE.md (Mermaid)
  - docs/data-flow.mmd

Drift since last gen (date: <last>):
  + Added: src/services/ (4 new modules)
  - Removed: vendor/sift-compress/ (extracted to companion)
  ~ Restructured: skills/ (subdirs for families)

Updated:
  ✓ ARCHITECTURE.md — added services/ block, removed vendor/ block
  ✓ docs/data-flow.mmd — no change (data flow unchanged)

Verification:
  ✓ All depicted nodes exist in repo
  ✓ All major modules represented
  ✓ Memorialised: <commit SHA>

Rules

• Incremental. Don't redraw what hasn't changed.
• Source-controlled diagrams. Mermaid in markdown beats binary draw.io.
• Verify before commit. Diagram must reflect current code.
• Capture to memory the regeneration as a snapshot — /siftcoder:knowledge can then track diagram drift over time.

Anti-patterns

• Regenerating from scratch every time (loses manual annotations)
• Diagrams that include every file (becomes unreadable; show top 2 levels)
• Stale diagrams left in place (rot signal)

When NOT to use

• No structural changes since last gen — skip
• Diagrams are auto-generated by typedoc / sphinx — regen via tool

Subagent dispatch

• Explore for current structure
• general-purpose for diagram editing
• Bash for Mermaid CLI rendering if needed

Value over native CC

CC will draw diagrams. CC won't naturally do incremental regen, drift detection vs last snapshot, or verify all depicted nodes exist. The incremental discipline IS the value.