From jaan-to
Generates GitHub-renderable Mermaid flowcharts from PRDs, docs, or codebases with evidence maps tracing nodes to sources. Useful for creating user flow diagrams.
How this skill is triggered — by the user, by Claude, or both
Slash command
/jaan-to:ux-flowchart-generateThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
> Generate GitHub-renderable Mermaid flowcharts from PRDs, docs, codebases, or any combination — with evidence maps tracing every node to its source, confidence scoring, and structured unknowns lists.
Generate GitHub-renderable Mermaid flowcharts from PRDs, docs, codebases, or any combination — with evidence maps tracing every node to its source, confidence scoring, and structured unknowns lists.
$JAAN_LEARN_DIR/jaan-to-ux-flowchart-generate.learn.md - Past lessons (loaded in Pre-Execution)$JAAN_TEMPLATES_DIR/jaan-to-ux-flowchart-generate.template.md - Output templates (flowchart + evidence map)$JAAN_CONTEXT_DIR/tech.md - Tech stack context (optional, auto-imported if exists)
#current-stack, #frameworks, #constraints${CLAUDE_PLUGIN_ROOT}/docs/extending/language-protocol.md - Language resolution protocolFlowchart Request: $ARGUMENTS
Parse as: [source_type] [paths...] [goal] [scope?]
| Param | Required | Values | Default |
|---|---|---|---|
source_type | Yes | prd, doc, repo, mixed | — |
paths | Yes | Space-separated file/directory paths | — |
goal | Yes | userflow, systemflow, architecture, stateflow | userflow |
scope | No | Free text to narrow focus (e.g., "checkout only", "auth module") | Entire source |
Optional: Screenshot paths can be provided alongside source files for visual context. UI screenshots will be embedded in the output as  alongside relevant subgraphs.
Output:
$JAAN_OUTPUTS_DIR/ux/diagrams/{id}-{slug}/
├── {id}-flowchart-{slug}.md # Diagram + unknowns + metrics
└── {id}-evidence-map-{slug}.md # Traceability table + mismatches
MANDATORY — Read and execute ALL steps in: ${CLAUDE_PLUGIN_ROOT}/docs/extending/pre-execution-protocol.md
Skill name: ux-flowchart-generate
Execute: Step 0 (Init Guard) → A (Load Lessons) → B (Resolve Template) → C (Offer Template Seeding)
Also read tech context if available:
$JAAN_CONTEXT_DIR/tech.md - Know the tech stack for code parsing in repo/mixed modesRead and apply language protocol: ${CLAUDE_PLUGIN_ROOT}/docs/extending/language-protocol.md
Override field for this skill: language_ux-flowchart-generate
Parse $ARGUMENTS to identify source type, file paths, goal, and optional scope.
For each path:
**/*.md, **/*.txt, **/*.pdfCheck for existing output (update mode):
If flowchart.md already exists at the expected output path:
@sources comment from the existing Mermaid block@generated timestamp%% ===== MANUAL (DO NOT AUTO-EDIT) ===== markersclassDef added fill:#D1FAE5,stroke:#059669classDef modified fill:#FEF3C7,stroke:#D97706Build input summary:
INPUT SUMMARY
════════════════════════════════════════
Source type: {prd|doc|repo|mixed}
Goal: {userflow|systemflow|architecture|stateflow}
Scope: {scope or "Entire source"}
Mode: {New | Update (incremental) | Update (full regen)}
Files to analyze: {N} files
PRD/docs: {n} files
Source code: {n} files
════════════════════════════════════════
Based on source_type, extract entities:
| Source type | Extract |
|---|---|
prd / doc | Screens, user actions, decisions, error cases, permissions, stated requirements |
repo | API routes, page/component exports, middleware chains, service calls, error handlers, state machines |
mixed | Both of the above, cross-referenced |
For repo / mixed modes — code parsing patterns by tech stack:
Read $JAAN_CONTEXT_DIR/tech.md if available. Otherwise infer from file extensions.
| Language | Glob Patterns | Grep Patterns |
|---|---|---|
| TypeScript/JS | **/routes/**/*.ts, **/api/**/*.ts, **/pages/**/*.tsx | export (const|function), router\.(get|post|put|delete), if \(, try {, catch \( |
| Python | **/views/**/*.py, **/api/**/*.py | def \w+\(, @app\.route\(, @router\.(get|post), try:, except |
| Go | **/handlers/**/*.go, **/api/**/*.go | func \w+\(, r\.GET\(|r\.POST\(, if err != nil |
| PHP | **/controllers/**/*.php, **/routes/**/*.php | function \w+\(, Route::(get|post), try {, catch \( |
Build an intermediate graph model:
| Input available | Goal | Diagram type |
|---|---|---|
| PRD only | userflow | flowchart — decision branches, multiple entry/exit |
| PRD only | stateflow | stateDiagram-v2 — when >4 distinct states with non-trivial transitions |
| Codebase only | systemflow | flowchart — derived from code structure, API routes, service calls |
| Codebase only | architecture | flowchart with subgraphs per service/module |
| Mixed | userflow | flowchart — user-facing paths from PRD, system detail from code, mismatch callouts |
| Mixed | any | Merge both; highlight mismatches with classDef mismatch |
Before generating, plan the diagram:
If splitting needed, plan Overview + Detail diagram breakdown:
sub_{name}[[See: {slug}-detail-{name}.md]]Ask using AskUserQuestion (skip questions already answered by input):
Audience: "Who is the primary audience?"
Update mode (if existing diagram detected): "How should I handle the existing diagram?"
Scope confirmation (if scope was provided): "Narrowing to '{scope}' — should I include related error paths and edge cases, or only the happy path?"
Present planned diagram structure for approval:
DIAGRAM PLAN
════════════════════════════════════════
Source: {source_type} — {comma-separated paths}
Goal: {goal}
Scope: {scope or "Entire source"}
Diagram type: {flowchart | stateDiagram-v2}
Direction: {TD | LR}
PLANNED STRUCTURE:
Nodes: {N} total ({N entry, N process, N decision, N success, N error})
Edges: {N} total ({N happy, N error, N mismatch})
Subgraphs: {N} ({names if applicable})
Estimated complexity: Cyclomatic {N}
SPLITTING: {Not needed | Will split into {N} diagrams}
SOURCE COVERAGE:
PRD sections analyzed: {N}/{total}
Code files analyzed: {N}/{total}
Gaps detected: {N} (entities in one source but not the other)
CONFIDENCE PREVIEW:
Expected 🟢 High: {N} nodes
Expected 🟡 Medium: {N} nodes
Expected 🔴 Low: {N} nodes
Expected ⚫ Unknown: {N} nodes
════════════════════════════════════════
"Proceed with diagram generation? [y/edit/n]"
Do NOT proceed to Phase 2 without explicit approval.
If edit: Ask "What should be changed?" and return to appropriate step If n: Stop and ask for next steps
Generate slug from the flow name:
password-reset-flowSource ID generator utility:
source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/id-generator.sh"
Generate sequential ID and output paths:
SUBDOMAIN_DIR="$JAAN_OUTPUTS_DIR/ux/diagrams"
mkdir -p "$SUBDOMAIN_DIR"
NEXT_ID=$(generate_next_id "$SUBDOMAIN_DIR")
slug="{generated-slug}"
OUTPUT_FOLDER="${SUBDOMAIN_DIR}/${NEXT_ID}-${slug}"
MAIN_FILE="${OUTPUT_FOLDER}/${NEXT_ID}-flowchart-${slug}.md"
EVIDENCE_FILE="${OUTPUT_FOLDER}/${NEXT_ID}-evidence-map-${slug}.md"
Preview output configuration:
"Output Configuration
- ID: {NEXT_ID}
- Folder: $JAAN_OUTPUTS_DIR/ux/diagrams/{NEXT_ID}-{slug}/
- Flowchart: {NEXT_ID}-flowchart-{slug}.md
- Evidence map: {NEXT_ID}-evidence-map-{slug}.md"
Apply ALL of the following rules. These are non-negotiable.
Reference: Full node shape mapping table (9 UX concepts with Mermaid syntax) and ID conventions (prefixes, reserved words, naming rules) in
docs/extending/ux-flowchart-reference.md→ Node Shapes / Node ID Conventions.
?; Error labels always start with "Error:"userflow, technical for systemflow, mixed uses evidence map for technical detailReference: Full edge type table (6 types with syntax and label format) in
docs/extending/ux-flowchart-reference.md→ Edge Conventions.
|success| or |next|-->|Yes| and -->|No| (not True/False, not unlabeled)subgraph when diagram has >15 nodessubgraph sg_auth ["Authentication"]Reference: Full classDef declarations (5 styles with hex color codes) in
docs/extending/ux-flowchart-reference.md→ Style Definitions.
Structure the Mermaid block in this exact order for clean git diffs:
flowchart {TD|LR}
%% @generated-by: jaan-to:ux-flowchart-generate
%% @sources: {comma-separated source file paths}
%% @generated: {ISO-8601 timestamp}
%% @version: 1.0.0
%% === NODES ===
{all node declarations, grouped by subgraph if applicable}
%% === EDGES: Happy Path ===
{primary flow edges}
%% === EDGES: Error Paths ===
{error/fallback edges}
%% === EDGES: Mismatch (PRD ↔ Code) ===
{only in mixed mode}
%% ===== MANUAL (DO NOT AUTO-EDIT) =====
{preserved across regenerations}
%% ===== END MANUAL =====
%% === STYLES ===
classDef error fill:#FEE2E2,stroke:#DC2626,color:#991B1B
classDef success fill:#D1FAE5,stroke:#059669,color:#065F46
classDef decision fill:#FEF3C7,stroke:#D97706,color:#92400E
classDef entry fill:#DBEAFE,stroke:#2563EB,color:#1E40AF
classDef mismatch fill:#FEF3C7,stroke:#DC2626,stroke-width:3px,stroke-dasharray:5 5
{class assignments}
Every generated diagram MUST include:
Reference: Full GitHub Mermaid rendering limits (v11.4.1: character caps, edge limits, security restrictions, layout engine) in
docs/extending/ux-flowchart-reference.md→ GitHub Rendering Constraints.
For every node in the diagram, create a row in the evidence map:
| Column | Description | Required |
|---|---|---|
| Node ID | Exact ID from diagram | Yes |
| Node Label | Human-readable label | Yes |
| PRD Reference | Section/heading in PRD (e.g., PRD §2.1) | If source includes PRD |
| Code Path | File path + line number (e.g., src/auth.ts:42) | If source includes code |
| Code Symbol | Function/class name (e.g., AuthMiddleware.verify()) | If source includes code |
| Test Path | Test file covering this node | If discoverable |
| Confidence | 🟢 High / 🟡 Medium / 🔴 Low / ⚫ Unknown | Yes |
| Status | FOUND / INFERRED / MISMATCH / UNKNOWN | Yes |
| Notes | Free text — why this confidence, what's missing | Yes |
Reference: Full confidence scoring table (4 levels with criteria) and derivation rules in
docs/extending/ux-flowchart-reference.md→ Confidence Scoring.
For mixed source mode:
FOUNDMISMATCH (PRD-only)MISMATCH (code-only)INFERREDFor single source modes (prd, doc, repo):
FOUNDINFERREDUNKNOWNGenerate a structured Unknowns table:
| Column | Description |
|---|---|
| ID | Sequential: U1, U2, ... |
| Unknown | What couldn't be determined |
| Impact | 🔴 High / 🟡 Medium / 🟢 Low |
| Source Gap | What's missing (PRD silent? Code absent? Test missing?) |
| Suggested Resolution | Concrete next step to resolve |
Mismatch callouts (mixed mode only): when PRD specifies something the code doesn't implement (or vice versa):
MISMATCH row to the evidence map:::mismatch styling and a ⚠️ label# | Description | PRD Says | Code Does | Severity | RecommendationRun ALL checks before writing output.
Reference: Full quality gate checklist (17 hard-fail gates, 2 warn gates, 5 human-review flags) in
docs/extending/ux-flowchart-reference.md→ Quality Gate Checklist.
If any hard-fail gate fails: fix the issue, then re-validate until all gates pass.
Show both outputs in conversation:
"Preview: Flowchart Outputs
{display flowchart.md content}
{display evidence-map.md content}
Quality gates: {N}/17 passed, {N} warnings, {N} human-review flags
Write these outputs? [y/n]"
If n: Ask "What should be changed?" and return to appropriate step
If screenshot paths were provided as input:
Reference: See
${CLAUDE_PLUGIN_ROOT}/docs/extending/asset-embedding-reference.mdfor the asset resolution protocol (path detection, copy rules, markdown embedding).
Source ${CLAUDE_PLUGIN_ROOT}/scripts/lib/asset-handler.sh. For each screenshot: check is_jaan_path — if inside $JAAN_*, reference in-place; if external, ask user before copying. Use resolve_asset_path for markdown-relative paths.
If approved, write files:
mkdir -p "$OUTPUT_FOLDER"
Write flowchart file to $MAIN_FILE
Write evidence map file to $EVIDENCE_FILE
Update subdomain index:
source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/index-updater.sh"
EXEC_SUMMARY="{extract 1-2 sentence overview from flowchart}"
add_to_index \
"$SUBDOMAIN_DIR/README.md" \
"$NEXT_ID" \
"${NEXT_ID}-${slug}" \
"{Flow Name}" \
"$EXEC_SUMMARY"
If update mode, include a ## Changelog section at the bottom of flowchart.md showing what changed and why.
Confirm completion:
"✓ Flowchart written to: $JAAN_OUTPUTS_DIR/ux/diagrams/{NEXT_ID}-{slug}/{NEXT_ID}-flowchart-{slug}.md ✓ Evidence map written to: $JAAN_OUTPUTS_DIR/ux/diagrams/{NEXT_ID}-{slug}/{NEXT_ID}-evidence-map-{slug}.md ✓ Index updated: $JAAN_OUTPUTS_DIR/ux/diagrams/README.md"
"Any feedback or improvements needed? [y/n]"
If yes:
"How should I handle this? [1] Fix now - Update this flowchart [2] Learn - Save for future flowcharts [3] Both - Fix now AND save lesson"
Options:
/jaan-to:learn-add ux-flowchart-generate "{feedback}"$JAAN_OUTPUTS_DIR pathnpx claudepluginhub parhumm/jaan-to --plugin jaan-toWrites Markdown documents and text-based Mermaid diagrams with style guides, 24 diagram-type references, and 9 document templates. Use for scientific documents, reports, READMEs, or version-controllable diagrams.
Creates scientific documents and diagrams using markdown with embedded Mermaid. Default format for version-controlled documentation, enabling clean diffs and no build steps.
Generates interactive HTML architecture diagrams with animated step-by-step flows, mode toggles, and side panel details. For service maps, CI/CD pipelines, data flows, and workshop diagrams.