PM - Diagrams

Agent mode (--agent)

Supports --agent: runs autonomously in a subagent, drafts the diagram from existing inputs, and returns a short summary + coverage note.

• No flag → interactive (default); if inputs are heavy, offer agent mode.
• --agent → obey. First check inputs are complete. Anything missing: do NOT invent it - mark [ASSUMED - what/why] in the output and summary. Never hallucinate to fill a gap.

Standalone run

Runs with or without a Pureinn workspace - it needs no other skill's artifact, so it works as a single tool from an install that never ran /pureinn.

• No workspace: create just the folder this skill writes into, or write to a path the user names, and say where the file went. Do not scaffold a project, do not invent a state.json, and do not send the user to /pureinn first.
• Read pureinn-variables.md / state.json where a value is actually used, not at the top of the run. Missing value: continue and name the capability it costs.

What this skill does

Generates visual diagrams. It is a rendering engine + composition knowledge utility: it owns how each diagram type is correctly composed, not the analysis behind it. The correct composition rules for every type live in references/[slug].md - the skill reads the relevant reference before drawing, so it never renders from memory.

Two rendering modes:

• Mermaid.js (primary, Claude Code workflow) - rendered inline in markdown, embedded in live registers and Feature Cards. Claude reads Mermaid natively. Use for anything that must be read as a specification.
• Excalidraw (secondary, human communication) - hand-drawn visual overviews for stakeholders. Use for high-level maps where the value is visual, not machine-readable.

The 18-type catalogue (slug → type)

"Render for" ownership (dependency, kanban, gantt, kano, swot): the analysis is owned by another skill. This skill only renders it. Read the data from the owning artifact; if the analysis does not exist yet, route to the owning skill rather than inventing the analysis. Never fabricate a Kano classification, SWOT factors, dependency edges, a lifecycle status, or a dated plan. For kanban, read status from feature_list.md / Feature Cards - never advance or invent a status to fill a column (status = code reality, owned by pm-stripe).

Step 0: Route by argument

If a slug was passed (/pm-diagrams bpmn, /pm-diagrams erd, ...): skip the menu. Go straight to Step 1 for that type. If the slug is unknown, show the catalogue and ask which was meant.

If no argument was passed: run the context-aware recommendation below - do not dump a generic menu.

Context-aware recommendation (no argument)

1. Read state.json (or scan the workspace) → current phase + which artifacts exist.
2. Detect visual gaps - an artifact exists but its diagram does not:

3. Rank by proximity to the current phase (closest to active work first).
4. Use the AskUserQuestion tool: offer the top 3 context-relevant recommendations, each with the reason it fits the current state, plus an "Other - pick from the full catalogue" option. Mark the highest-ROI one (Recommended).

This is the active form of the "situation-aware + proactive" standard: read state, propose the highest-value visual for the current position, never a fixed script. (Full interaction standard: CLAUDE.md.)

Step 1: Load the composition reference

Before gathering inputs or drawing, read references/[slug].md for the selected type. It carries the element vocabulary, composition rules, canonical structure, anti-patterns, Mermaid/Excalidraw rendering notes, required inputs, and a worked example. Compose strictly to that reference - it is the source of correctness for the diagram's form.

For "render for" types (dependency, gantt, kano, swot): also locate the owning artifact named in the reference's "Source of truth". If it is missing, route to the owning skill instead of inventing the analysis.

Step 2: Gather inputs

Use the Required inputs list in the loaded reference. Gather them from:

1. The source-of-truth artifact first (see rule below), then
2. The user, for anything not in an artifact.

Interaction: group related questions (2-4 per round) and confirm before drawing. For any A/B/C/D choice, use the AskUserQuestion tool with one option marked (Recommended) - never print options as plain text. Keep open-ended questions free-text. If the user is unsure, propose 3-4 concrete options plus "Other". Surface an assumption the moment you make one; never fabricate to fill a gap. (Full standard: CLAUDE.md.)

Source-of-truth rule: when the content being diagrammed lives in a register (entities.md, business_rules.md, feature_list.md, process-flows, roadmap), read the register first and diagram what it says - never render from memory or from the user's paraphrase alone. If the user's description conflicts with the register, flag the divergence before drawing; a polished diagram of stale content is worse than no diagram, because people trust visuals more than they trust files.

Step 3: Generate the diagram

Render per the reference's Rendering notes:

• Mermaid types → emit a fenced ```mermaid block. Optionally validate/repair with the mermaid MCP (mcp__mermaid__validate_and_render_mermaid_diagram) before finalizing.
• Excalidraw types → render with the Excalidraw MCP (mcp__claude_ai_Excalidraw__create_view) if available; otherwise fall back to the Mermaid approximation named in the reference and note that Excalidraw was unavailable.

Follow the reference's element vocabulary, composition rules, and color semantics exactly. Order Excalidraw elements for clean streaming (background zone → shape → label → arrow).

Step 4: Export / checkpoint (optional, Excalidraw only)

After rendering an Excalidraw diagram, use the AskUserQuestion tool:

• Option A: "Export to excalidraw.com - shareable link for editing"
• Option B: "Save checkpoint - continue editing in a future session (Recommended)"
• Option C: "Done"

If A: call mcp__claude_ai_Excalidraw__export_to_excalidraw and return the URL. If B: note the checkpoint ID from create_view; it can be restored with /pm-diagrams later.

Mermaid diagrams are already embedded in markdown - no export step needed.

Notion push

After generating a diagram, update the Diagrams page in Notion.

1. Read pureinn-variables.md key "Diagrams" → get Page URL.
2. If blank: skip, remind user to add URL to pureinn-variables.md.
3. Call mcp__claude_ai_Notion__notion-update-page with command: "insert_content":

## [Diagram Name] — [date]

**Type:** [type] (`[slug]`)
**Feature/Context:** [FEAT-ID or phase context]

[Mermaid code block, or Excalidraw URL / "Excalidraw checkpoint"]

Keeps the Diagrams page as a running catalogue of all generated visuals.

Internal completeness checklist

Before generating:

• Slug resolved (argument) or recommended from workspace state (no argument)
• references/[slug].md read
• For "render for" types: owning artifact located, or routed to owning skill
• Required inputs gathered from source-of-truth first, then user
• Correct tool (Mermaid vs Excalidraw) per the reference

After generating:

• Composition matches the reference (vocabulary, rules, structure)
• All elements labeled and readable (Excalidraw font ≥ 16)
• Mermaid validated (if MCP available)
• Notion push done (or skipped with reason)

Handoff

Čo si teraz má: Konkrétny diagram ([type]) zložený podľa správneho notačného štandardu - použiteľný v dokumentácii, registri alebo na komunikáciu.

Ďalší krok: Pokračuj v aktuálnej fáze - /pm-diagrams je cross-phase utilita, spúšťaj ho kedykoľvek treba vizuál (/pm-diagrams [slug] pre konkrétny typ). /pureinn ukáže ďalší krok podľa fázy.

Môžeš preskočiť ak: diagram daného typu už existuje a je aktuálny - regeneruj len keď sa zmenil zdrojový register.