/concept-map

name: concept-map
description: Turn a topic, chapter, or pasted source into a visual graph — mind maps, concept maps, prerequisite trees, cause-effect networks, taxonomies, process flows, or timelines. Triggers on student phrasings like "mind map of the french revolution", "concept map for photosynthesis", "show me how these ideas relate", "visualize this chapter", "map out the relationships in this reading", "map my notes", and on teacher phrasings like "diagram of this chapter for my 7th graders", "prerequisite tree for calculus", "cause and effect map of WWI", "draw a taxonomy of vertebrates", "flowchart the scientific method", "timeline of the civil rights movement", "markmap of these notes". Emits Mermaid (default), Graphviz DOT, or Markmap syntax plus an optional rendered PNG/SVG via the bundled renderer — falls back to syntax + install hints when renderers are missing. Calibrates node count and vocabulary to grade level.

concept-map

Turn a topic string or source text into a legible graph that shows structure at a glance. Default output is Mermaid syntax (renders in GitHub, Notion, Obsidian, and Claude Code with zero install) plus a PNG/SVG when a renderer is available.

When to trigger

Activate on any phrasing that asks to *visualize relationships between ideas*. Examples:

Student phrasings

• "mind map of the french revolution"
• "concept map for photosynthesis"
• "show me how these ideas relate"
• "visualize this chapter as a graph"
• "map my notes on cell biology"
• "I need a mind map to study for my exam"

Teacher phrasings

• "diagram of this chapter for my 7th graders"
• "prerequisite tree for calculus"
• "cause and effect map of WWI"
• "draw a taxonomy of vertebrates"
• "flowchart the scientific method"
• "timeline of the civil rights movement"
• "markmap of my unit notes"

Anti-triggers — DO NOT invoke

• "write me a summary of X" → plain prose, not a graph.
• "give me a flowchart for this React component" → code-diagramming, out of scope.
• "draw a picture of a cell" → labeled illustration, not a concept graph.

Inputs

• **Topic string** *(required OR source)* — "the French Revolution", "photosynthesis", "derivatives".
• **Source text** *(required OR topic)* — pasted chapter, notes, or article paragraphs.
• **Graph type** *(optional)* — `tree`, `concept-map`, `flow`, `timeline`, `mindmap`. Inferred if omitted (see table below).
• **Format** *(optional)* — `mermaid` (default), `dot`, `markmap`, or `all`.
• **Grade / level** *(optional)* — K-2, 3-5, 6-8, 9-12, college, grad. Drives node count + vocabulary.
• **Max nodes** *(optional)* — integer, default 20, hard cap 50.
• **Render** *(optional, default true)* — auto-invoke `scripts/render.py` to produce PNG/SVG.

Inferring graph type from phrasing (before asking)

Pick the graph type from the user's wording — do NOT ask unless both topic and format are absent.

| Phrasing cue | Graph type | Mermaid directive | |---|---|---| | "timeline of", "history of", "events leading up to", "chronology" | timeline | `timeline` | | "parts of a ___", "anatomy of", "taxonomy of", "types of", "classification" | tree (hierarchical) | `graph TD` | | "prerequisite tree", "what do I need before", "dependency graph" | tree (bottom-up DAG) | `graph BT` or DOT `rankdir=BT` | | "causes of ___", "cause and effect", "what led to" | concept map with labeled edges | `graph LR` with edge labels | | "how does ___ work", "process of", "steps in", "scientific method" | flow (process) | `flowchart LR` | | "mind map of", "brainstorm", "everything about ___", "map my notes" | radial mindmap | `mindmap` | | "concept map", "how these ideas relate", "relationships between" | Novak concept map | `graph TD` with labeled edges + cross-links | | "markmap", "outline of my notes", "heading tree" | Markmap | Markdown headings |

If both topic AND format are missing, ask ONE clarifying question in this exact shape:

> Quick check — what topic, and which flavor? (e.g. **mind map of the French Revolution · concept map for photosynthesis · prerequisite tree for calculus · timeline of WWII**)

Do not stack questions. Once the user answers, proceed straight to generation.

Grade / level calibration

| Level | Nodes | Structure | Edge labels | |---|---|---|---| | K-2 | 3-5 | Simple radial mindmap | None (lines only) | | 3-5 | 6-10 | Hierarchical tree | Simple ("is a", "has") | | 6-8 | 10-15 | Tree or concept map | Verbs ("causes", "requires") | | 9-12 | 15-25 | Concept map with cross-links | Full labeled propositions | | College | 20-40 | Concept map, multiple clusters | Rich labels | | Grad | Up to 50 | Concept map + subgraphs / process flows | Precise terminology |

Vocabulary tracks level: K-2 uses common words, grad uses domain-precise terms.

Workflow

1. **Parse** the request — extract topic OR source, graph type, format, grade. 2. **Infer** graph type from the table above if not specified. Default format is Mermaid. 3. **Extract** 10-30 candidate key concepts. Respect `max-nodes`. 4. **Cluster** related concepts; pick the root / central concept. 5. **Draft relationships.** For concept maps, label every edge with a verb or preposition ("causes", "is-a", "requires", "leads to"). See `references/novak-concept-maps.md`. 6. **Emit syntax** — write the chosen format to disk (`concept-map.mmd` by default). 7. **Render** — if `render: true`, invoke `scripts/render.py --input concept-map.mmd --output concept-map.png`. Script falls back to install hints if the CLI is missing; the syntax file is always preserved. 8. **Summarize** — return root concept, node count, edge count, and file paths.

Locked defaults

| Setting | Default | |---|---| | Format | Mermaid (`graph TD` or per inference table) | | Render | Auto-invoke `scripts/render.py` when the user asks for a rendered image; otherwise emit syntax + one-line render instructions | | Max nodes | 20 (hard cap 50) | | Cross-links | Enabled for grades 9-12 and above | | Edge labels | Requir