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.
1---2name: concept-cartographer-23description: 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".4---56# Concept Cartographer — Visual Knowledge Mapper78**Audience:** Agents transforming lecture notes or technical documentation into visual diagrams.9**Goal:** Generate Mermaid diagrams tuned to the content's domain and verified against the source topic inventory — not a syntax dump.1011## Diagram Type Selection1213Claude 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.1415| Diagram type | Use when content has | Typical size |16|---|---|---|17| Concept hierarchy (`graph TD`) | Parent-child topic structure, taxonomies | 5–15 nodes |18| Process flowchart (`flowchart LR`) | Algorithms, workflows, decision branches | 5–12 nodes |19| Architecture (`graph LR` + subgraphs) | System components + data flow | 3–4 subgraphs, 10–15 nodes |20| Sequence (`sequenceDiagram`) | Interactions over time, API/protocol flows | 3–6 participants, 8–15 messages |21| State (`stateDiagram-v2`) | Lifecycle, mode transitions | 4–10 states |22| Comparison (`graph TD` with branches) | Alternatives with trade-offs | 2–4 branches, ≤4 leaves each |23| Learning-path (`graph LR` with prerequisites) | Educational content with built-up concepts | 5–12 nodes |24| Quadrant (`quadrantChart`) | Difficulty-vs-importance prioritization | 4–10 points |2526## Domain-Specific Focus2728| Domain | Priority diagrams | Special elements |29|---|---|---|30| AI/ML | Architecture, process flow, comparison | Layer structures, training loops, model pipelines |31| WebDev | Architecture, sequence, flowchart | Request/response flows, component trees, state |32| Web3 | Sequence, architecture, state | Transaction flows, contract interactions, token flows |33| DSA | Flowchart, state, comparison | Algorithm steps, tree/graph structures, complexity |3435## Topic Inventory Verification3637If 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.3839Report at the end:4041```markdown42## Concept Coverage43- Concepts in diagrams: [N] / [N] from inventory44- Concepts not diagrammed: [list] (reason: "too granular" or "no visual relationship")45```4647If no inventory exists, extract topics from the source notes before drawing — treat your own extraction as the inventory and verify against it.4849## Output Format5051```markdown52# Visual Concept Maps: [Topic]5354## Overview Map55[Always include: concept hierarchy — this is the minimum output]5657## [Diagram Type 2]58[Most relevant additional diagram, with 1–2 sentence caption]5960## [Diagram Type 3]61[Second most relevant, with caption]6263## Key Relationships Summary64- [Concept A] depends on [Concept B] because...65- [Concept C] is an alternative to [Concept D] when...6667## Concept Coverage68[Verification report]69```7071## Rules72731. **Valid Mermaid, verified mentally before output.**742. **Always include a concept hierarchy** — minimum output.753. **Pick 2–4 diagram types per note set**; more is noise.764. **Every diagram gets a 1–2 sentence caption** naming its purpose.775. **Max 15 nodes per diagram** — split into sub-diagrams with explicit cross-links beyond that.786. **Use subgraphs** for grouping related concepts.797. **Match the domain** — use domain-appropriate terminology.808. **Verify against the topic inventory** before declaring done.8182## Anti-Patterns8384- **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.85- **NEVER** stuff more than 15 nodes into a single diagram — readability collapses. Split into sub-diagrams with explicit cross-links (`see: Diagram 3`).86- **NEVER** skip the verification pass against the source topic inventory. A diagram that silently drops 30% of topics is more misleading than no diagram.87- **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.88- **NEVER** embed a diagram without a 1–2 sentence caption naming its purpose — visual without verbal context is noise the reader has to decode.89- **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.90- **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.9192## Pipeline Position9394Stage 3 in the lecture processing pipeline:95961. `transcribe-refiner` produces the clean transcript plus Topic Inventory.972. `lecture-alchemist` produces structured study notes.983. `concept-cartographer` (this) produces visual diagrams, verified against the inventory.994. `obsidian-markdown` applies Obsidian vault formatting.100101## References102103- `references/mermaid-examples.md` — one worked example per diagram type. Load on demand.
praxstack