explain-complex-code

Files (3)

• SKILL.md
• documentation-template.md · references/
• examples.md · references/

SKILL.md (first lines)

# Explain Complex Code

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

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

Find all symbols in the area and identify the high-dependency ones (most importers).

**Step 2.2: Map Dependencies**
For each key class/function: find its callers across the source tree, and read its body for the callees it uses.

**Step 2.3: Decide Partitioning Strategy**

Partition by file count, keeping each directory that forms one logical block together:

| 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

From broneq/bdk, MIT.

More from broneq/bdk