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:

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