# Explain Complex Code

> Generate comprehensive architecture documentation for complex code modules with Mermaid diagrams and examples. Use when user asks to "explain this code", "document the architecture", or wants to understand how a module/system works.

- Skill: `broneq/explain-complex-code` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add broneq/explain-complex-code`
- Raw SKILL.md: https://api.skillmd.com/api/skills/broneq/explain-complex-code/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/explain-complex-code

---


# Explain Complex Code

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

Generate architecture docs for complex code with visual diagrams and examples.

## Workflow

### 1. Understand Scope

`path` arg specifies code to explain. Clarify:
- **Focus areas**: Architecture, algorithms, data flow, testing strategy
- **Audience level**: Team onboarding, external docs, debugging guide

### 2. Analyze Code Structure

**Step 2.1: Initial Discovery**

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

Using the exploration tools above: find all symbols, identify high-dependency symbols, use community grouping to determine subagent partitioning where available.

**Step 2.2: Map Dependencies**
For each key class/function: `query_graph(pattern="callers_of", node=<symbol>)` and `query_graph(pattern="callees_of", node=<symbol>)`. Fall back to Serena `find_referencing_symbols` if graph unavailable.

**Step 2.3: Decide Partitioning Strategy**

When graph communities are available, use community boundaries as partitioning units — one community per subagent. Otherwise fall back to file-count rules:

| Files Count | Strategy | Subagent Count |
|-------------|----------|----------------|
| 1-2 files | One subagent for entire module | 1 subagent |
| 3-5 files | Group into 1-2 logical blocks | 1-2 subagents |
| 6-10 files | Group into 2-3 logical blocks | 2-3 subagents |
| 10+ files | Group by architectural layers | 3-4 subagents |

**Never more than 3-4 subagents.**

### 3. Launch Subagents Strategically

Launch ALL subagents in ONE message. Per subagent:

```
Explore the following files as a logical block: [FILE_LIST]

For EACH file, report:
1. Core responsibilities and purpose
2. Key classes/functions and their roles
3. Important dependencies
4. Critical algorithms or rules
5. Data structures
6. Edge cases or special handling

Then synthesize:
7. How these files work together
8. Data flow between them
9. Shared dependencies or patterns
```

### 4. Synthesize Documentation

From subagent findings, create structured docs.

**Structure:**
1. **Overview**: 2-3 sentence summary
2. **Core Architecture**: File tree + component diagram
3. **Architecture Flow**: Process flow with Mermaid
4. **Critical Rules**: Non-obvious rules with examples
5. **Live Examples**: Prototype code (NOT actual implementation)
6. **Core Classes**: Key classes with usage patterns
7. **Testing Coverage**: Existing test structure and patterns

### 5. Create Mermaid Diagrams

Embed diagrams directly as fenced ```mermaid``` code blocks — no separate source file, no compile step, renders natively wherever the doc is viewed.

**Follow `/bdk:mermaid-drawer`** for type selection, node budget and colour. It is the shared standard across every BDK skill that emits a diagram, so docs from different skills read alike. Architecture docs typically need a component `flowchart` with one `subgraph` per layer; add a `sequenceDiagram` when the module's behaviour is a call chain across boundaries, and a `stateDiagram-v2` when it drives an entity through named states.

### 6. Write Prototype Examples

**CRITICAL RULE**: Prototype code only — NOT actual implementation.

**Good Prototype:**
```
# Parse and validate
parsed = parse(input_data)
if not parsed.is_valid:
    return error_response()

# Transform based on type
result = transform(parsed)
return format_output(result)
```

**Prototype Rules:**
- Placeholder function names
- Clear control flow
- Comments for key steps
- Under 20 lines per example
- One concept per example

### 7. Save Documentation

Save to `.bdk/explain-complex-code/[feature-name].md`.

## Quality Checklist

- [ ] Overview (2-3 sentences)
- [ ] File tree
- [ ] At least one Mermaid diagram
- [ ] Critical rules with examples
- [ ] Live examples with prototype code
- [ ] Core classes with usage
- [ ] Testing coverage

## Notes

- **Prototype code mandatory**: Never copy actual implementation
- **Parallel subagents save time**: Launch all in one message
- **Focus non-obvious details**: Skip basic patterns