# Update Docs

> Use when existing architecture documentation needs refreshing after code changes, when running periodic doc maintenance, or when user asks to "update docs", "refresh documentation", or "sync docs with code".

- Skill: `broneq/update-docs` (Agent Skill)
- Install (CLI): `npx skillmds@latest add broneq/update-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/broneq/update-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: broneq (https://skillmd.com/u/broneq)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/broneq/update-docs

---


# Update Docs

> Relies on BDK foundation (STARTUP_INSTRUCTIONS.md) for project context and MCP tool preference.

!`python3 ${CLAUDE_PLUGIN_ROOT}/scripts/inject.py --chain ${CLAUDE_PLUGIN_ROOT}/fragments/tool-tiers/explore.chain.json`

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**

```python
mcp__plugin_bdk_serena__list_dir(relative_path="<module_root>", recursive=True)
mcp__plugin_bdk_serena__get_symbols_overview(relative_path="<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`:

| Files Count | Subagent Count |
|-------------|----------------|
| 1-2 files   | 1 subagent     |
| 3-5 files   | 1-2 subagents  |
| 6-10 files  | 2-3 subagents  |
| 10+ files   | 3-4 subagents  |

**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

| Signal | Classification |
|--------|---------------|
| Symbol changed/renamed | Section OUTDATED |
| File added/removed | File tree OUTDATED |
| New undocumented symbol | Content MISSING |
| Referenced symbol gone | Section OUTDATED |
| Diagram references stale symbols | Diagram OUTDATED |
| New subsystem without diagram | Diagram MISSING |
| No discrepancies | Section ACCURATE |

### 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)