| name | concept-cartographer |
| description | Generate visual concept maps, flowcharts, architecture diagrams, and relationship diagrams from structured notes or technical content using Mermaid syntax. Use when the user has lecture notes, study materials, or technical documentation and wants visual diagrams to aid understanding. Produces multiple diagram types: concept hierarchy maps, process flowcharts, architecture diagrams, comparison matrices, timeline diagrams, and mind maps. Trigger phrases: "create diagrams from notes", "visualize concepts", "concept map", "make flowcharts", "diagram this", "visual notes". |
Concept Cartographer — Visual Knowledge Mapper
Audience: Agents transforming lecture notes or technical documentation into visual diagrams.
Goal: Generate Mermaid diagrams tuned to the content's domain and verified against the source topic inventory — not a syntax dump.
Diagram Type Selection
Claude already knows Mermaid syntax. The delta this skill provides is picking the right diagram type for the content and verifying coverage. One illustrative example per type is in references/mermaid-examples.md; load it only if a reminder is needed.
| Diagram type | Use when content has | Typical size |
|---|
Concept hierarchy (graph TD) | Parent-child topic structure, taxonomies | 5–15 nodes |
Process flowchart (flowchart LR) | Algorithms, workflows, decision branches | 5–12 nodes |
Architecture (graph LR + subgraphs) | System components + data flow | 3–4 subgraphs, 10–15 nodes |
Sequence (sequenceDiagram) | Interactions over time, API/protocol flows | 3–6 participants, 8–15 messages |
State (stateDiagram-v2) | Lifecycle, mode transitions | 4–10 states |
Comparison (graph TD with branches) | Alternatives with trade-offs | 2–4 branches, ≤4 leaves each |
Learning-path (graph LR with prerequisites) | Educational content with built-up concepts | 5–12 nodes |
Quadrant (quadrantChart) | Difficulty-vs-importance prioritization | 4–10 points |
Domain-Specific Focus
| Domain | Priority diagrams | Special elements |
|---|
| AI/ML | Architecture, process flow, comparison | Layer structures, training loops, model pipelines |
| WebDev | Architecture, sequence, flowchart | Request/response flows, component trees, state |
| Web3 | Sequence, architecture, state | Transaction flows, contract interactions, token flows |
| DSA | Flowchart, state, comparison | Algorithm steps, tree/graph structures, complexity |
Topic Inventory Verification
If a Topic Inventory was provided from Stage 1 (lecture pipeline), verify every concept from the inventory appears in at least one diagram. This is the coverage gate — a diagram missing 30% of topics is worse than no diagram.
Report at the end:
## Concept Coverage
- Concepts in diagrams: [N] / [N] from inventory
- Concepts not diagrammed: [list] (reason: "too granular" or "no visual relationship")
If no inventory exists, extract topics from the source notes before drawing — treat your own extraction as the inventory and verify against it.
Output Format
# Visual Concept Maps: [Topic]
## Overview Map
[Always include: concept hierarchy — this is the minimum output]
## [Diagram Type 2]
[Most relevant additional diagram, with 1–2 sentence caption]
## [Diagram Type 3]
[Second most relevant, with caption]
## Key Relationships Summary
- [Concept A] depends on [Concept B] because...
- [Concept C] is an alternative to [Concept D] when...
## Concept Coverage
[Verification report]
Rules
- Valid Mermaid, verified mentally before output.
- Always include a concept hierarchy — minimum output.
- Pick 2–4 diagram types per note set; more is noise.
- Every diagram gets a 1–2 sentence caption naming its purpose.
- Max 15 nodes per diagram — split into sub-diagrams with explicit cross-links beyond that.
- Use subgraphs for grouping related concepts.
- Match the domain — use domain-appropriate terminology.
- Verify against the topic inventory before declaring done.
Anti-Patterns
- NEVER use more than one diagram type for the same set of relationships (e.g., a flowchart AND a graph showing the same process). The reader has to mentally merge them, which defeats the diagram's purpose.
- NEVER stuff more than 15 nodes into a single diagram — readability collapses. Split into sub-diagrams with explicit cross-links (
see: Diagram 3).
- NEVER skip the verification pass against the source topic inventory. A diagram that silently drops 30% of topics is more misleading than no diagram.
- NEVER use Mermaid for data-heavy relationships (10+ columns, dense fact tables, wide ERDs) — prefer a markdown table or a dedicated ERD tool. Mermaid ERDs past ~8 entities become unreadable.
- NEVER embed a diagram without a 1–2 sentence caption naming its purpose — visual without verbal context is noise the reader has to decode.
- NEVER redraw the same hierarchy as both
graph TD and graph LR "to give options" — pick the one the content needs. Orientation is a decision, not a preference.
- NEVER mix abstraction levels in one diagram (e.g., a single flowchart showing both business workflow and function call sequence) — promote one to a subgraph or split entirely.
Pipeline Position
Stage 3 in the lecture processing pipeline:
transcribe-refiner produces the clean transcript plus Topic Inventory.lecture-alchemist produces structured study notes.concept-cartographer (this) produces visual diagrams, verified against the inventory.obsidian-markdown applies Obsidian vault formatting.
References
references/mermaid-examples.md — one worked example per diagram type. Load on demand.
