Update Docs

Relies on BDK foundation (STARTUP_INSTRUCTIONS.md) for project context.

Refresh existing architecture documentation by comparing it against current code, merging updates while preserving accurate manual prose. The result is uniform text — no changelog, no diff markers, no "updated on" annotations.

Workflow

1. Parse Existing Doc

Read the documentation file at $ARGUMENTS and extract:

• Sections: Split by ## headers into top-level sections
• Module root: From the file tree code block (e.g., src/data_migrator/processors/loaders/xml/)
• Code references: Class/function names from ### Class: patterns and code blocks
• File list: Parse file tree to get documented files
• Diagram references: Collect all embedded ```mermaid fenced blocks and their preceding headers

Do this in main context — no subagent needed. Use regex and string matching.

Fallback: If the doc lacks a clear file tree or module root, ask the user which code path the doc covers.

2. Explore Current Code

Step 2.1 — Discover Current State

List the files under the module root and the definitions in its key files.

Compare actual file list against the doc's file tree. Note added/removed/renamed files immediately.

Step 2.2 — Check Diagram References

For each diagram reference found in step 1:

1. Read the embedded Mermaid block content directly from the doc
2. Compare diagram content against current code: Do the nodes, edges, labels, and relationships in the diagram still match the actual classes, modules, and data flows?
3. Flag stale diagrams: If a diagram references renamed/removed symbols, missing components, or outdated relationships, mark it as OUTDATED
4. Flag missing diagrams: If new subsystems or major flows were added that have no diagram, mark as MISSING

Include diagram findings alongside code findings for subagents.

Step 2.3 — Partition into Logical Blocks

Same rules as /bdk:explain-complex-code:

Step 2.4 — Launch Comparison-Aware Subagents

CRITICAL: Launch all subagents in a SINGLE message with multiple Task tool calls.

Each subagent receives existing doc claims alongside files to explore:

Subagent Instructions Template:

Explore these files: [FILE_LIST]

The existing documentation claims:
[EXTRACTED_CLAIMS_PER_FILE]

The following diagrams reference these files:
[DIAGRAM_REFERENCES_FOR_THIS_BLOCK]

For EACH file, report:
1. What's ACCURATE in the existing docs
2. What's OUTDATED (changed signatures, renamed classes, different logic)
3. What's NEW (undocumented classes, methods, rules)
4. What's GONE (documented things that no longer exist)

For EACH referenced diagram, report:
1. Which nodes/edges still match the code
2. Which nodes/edges are stale (renamed, removed, restructured)
3. What new components should be added to the diagram

Also report: purpose, components, dependencies, key algorithms,
data structures, edge cases.

Format as:
## Block: [block name]
### Comparison Results:
- ACCURATE: [list]
- OUTDATED: [list with details of what changed]
- NEW: [list with details]
- GONE: [list]

### Diagram Results:
- [diagram name]: ACCURATE / OUTDATED (details) / MISSING new diagram needed

### Current State:
For each file:
#### File: [name]
- Purpose: [brief]
- Components: [list with descriptions]
- Dependencies: [list]
- Key Rules: [list]
- Special Cases: [list]

3. Confirm Update Plan

After subagents return, classify each section by content matching — no hardcoded section mapping.

Classification logic (generic, works with any template):

• Section mentions symbol X → subagent says X changed → OUTDATED
• Section has file tree → actual files differ → OUTDATED
• Subagent reports new symbol not mentioned anywhere → MISSING
• Section references symbol Y → subagent says Y no longer exists → OUTDATED
• Diagram references stale symbols or missing components → DIAGRAM OUTDATED
• New subsystem has no diagram → DIAGRAM MISSING
• No discrepancies found in section → ACCURATE (keep as-is)

Present the update plan and ask for confirmation in a single AskUserQuestion call:

Use AskUserQuestion with a single question. Put the full update plan in the question text:

Update plan for [doc_path]:

  KEEP:     [list of accurate sections]
  UPDATE:   [list of outdated sections with brief reason]
  ADD:      [new content to add]
  REMOVE:   [orphaned references to clean up]
  DIAGRAMS: [list of diagrams to update/add/keep with brief reason]

Approve this update plan?

Options: "Approve" / "Approve with changes" / "Cancel"

Only proceed to step 4 after user approves. If "Approve with changes", incorporate user feedback.

4. Write Updates

Reconstruct the document:

1. Copy unchanged sections verbatim (preserves manual prose, formatting, wording)
2. Rewrite outdated sections using patterns from /bdk:explain-complex-code references
3. Insert new content where it fits logically within existing structure
4. Remove orphaned references cleanly — no "removed" comments, just omit
5. Update diagrams - per /bdk:mermaid-drawer:
   • Rewrite outdated ```mermaid blocks to reflect current code structure
   • Add new diagrams for undocumented subsystems
   • Keep accurate diagrams unchanged. A diagram that is still correct but predates the standard is not "outdated" - leave it alone unless the code it describes moved, so updates stay reviewable as content changes rather than churn.

The final file reads as one uniform document. No markers indicating which parts were updated.

Prototype code rules (same as /bdk:explain-complex-code):

• Use placeholder names: process(), transform(), calculate()
• Show control flow clearly, include comments for key steps
• Keep under 20 lines per example
• Never copy actual implementation

5. Save

Save to the same path as the input $ARGUMENTS.

Resources

Documentation Template

Use /bdk:explain-complex-code references for section structure when rewriting outdated sections. Do not load unless rewriting sections.

Quick Reference

Update Classification

Checklist

• Parsed existing doc, extracted module root and diagram references
• Explored current code with comparison-aware subagents (including diagram checks)
• Classified each section and diagram (accurate/outdated/missing)
• Presented update plan and got user confirmation via single AskUserQuestion
• Wrote updates preserving accurate sections verbatim
• Updated/added/kept diagrams as approved
• Final document reads as uniform text (no update markers)