Process Flow Diagram Skill

Creates professional cross-functional (swimlane) process flow diagrams in Lucidchart using the Standard Import JSON format. This skill works across any project or domain — it is not tied to any specific system.

When to Use

• User asks to create a process flow diagram, flowchart, or swimlane diagram
• User uploads a requirements document (.docx, .pptx) and wants it visualized
• User describes a process in natural language and wants a diagram
• User wants to map out customer onboarding, payment flows, compliance processes, support workflows, or any business process

Lucid Safety Rules (Non-Negotiable)

These rules protect the user's existing Lucid workspace.

1. NEVER edit, modify, or delete any existing diagram — not even to "fix" or "improve" it.
2. Only operate on diagrams you created in the current session (you have the document ID from the create call), OR diagrams the user has explicitly told you to work on by name or URL.
3. Before any edit/delete operation, confirm the document ID matches one you created or one the user explicitly named.
4. When in doubt, create a new diagram rather than modifying an existing one.
5. Search is safe — search freely to find or reference diagrams, but results are read-only context, not edit permission.

Prerequisites

• Lucid MCP must be connected. If unavailable, inform the user.
• For .docx or .pptx files, use markitdown to extract text before processing.

Workflow

Phase 1: Understand the Process (Ask Smart Questions)

Before creating anything, gather the information needed to build an accurate diagram. The quality of the diagram depends entirely on how well you understand the process.

If the user provides a document (.docx, .pptx, or pasted text):

1. Extract the text using markitdown:

   pip install markitdown --break-system-packages 2>/dev/null && python -m markitdown "<path>"

2. Read the full extracted content carefully.
3. Identify: actors, systems, user actions, system behaviors, decision points, exceptions, and notes.
4. Present a summary of what you understood and ask confirming questions.

Whether from a document or conversation, ask these questions using the AskUserQuestion tool:

• Actors: "Who are the human actors in this process?" (e.g., System Administrator, Customer, Support Agent). Suggest based on what you've parsed.
• Systems: "What systems or applications are involved?" (e.g., CRM, Payment Gateway, ARS). This determines the legend.
• Swimlane count: Suggest the number of swimlanes based on the actors/systems you identified. Typical patterns:
  • 2 lanes: One human actor + one system (most common)
  • 3 lanes: Two human actors + one system, or one actor + two systems
  • 4+ lanes: Multiple actors and systems interacting
• Flow complexity: "Is this a single linear flow, or does it have multiple branches/sub-processes?" Suggest based on what you see in the requirements.
• Decision points: List the branching decisions you identified and confirm.
• Title: Suggest a title and subtitle for the diagram.
• Color theme: Offer the default professional palette (navy/teal/gold) or ask if they want custom colors.
• Legend systems: What system/application labels should appear in the legend?

Proactive suggestions you should make:

• If requirements mention CRUD operations (create, read, update, delete), suggest a single diagram with decision diamonds routing between the branches — this is more useful than four separate diagrams.
• If the flow has more than ~25 shapes, suggest splitting into multiple diagrams or pages.
• If the user hasn't mentioned notes/annotations, check the requirements for edge cases, exceptions, or business rules that should be called out.
• If actors are ambiguous (unclear whether human or system), flag it and suggest the most logical assignment.

Phase 2: Decompose into Flow Elements

Read references/diagram-patterns.md for the full pattern reference. Map each requirement to a flow element:

Shape-to-logic mapping — how to classify steps:

The distinction between shapes matters because it tells the reader who or what is performing the action:

• "User clicks Submit" → manualInput (human is acting)
• "System validates the input" → process (system is acting autonomously)
• "Form is displayed" → data (system is presenting information to the user)
• "Is the record valid?" → decision (a branching point in the flow)
• "Begin" / "End" → terminator (entry/exit points)

When requirements are ambiguous, apply this test: "Could this step happen without a human doing anything?" If yes → process. If no → manualInput. If the system is showing information to a human → data.

Phase 3: Map the Flow Sequence

1. Start with the Start terminator in the top-left of the actor lane
2. Sequence elements left-to-right following the natural process order
3. For each Decision diamond:
   • Yes → continues the main flow (typically forward or downward)
   • No → loops back, ends, or routes to an alternative path
   • Always label the outgoing connectors with "Yes" / "No"
4. Cross-lane transitions occur when a user action triggers a system process (vertical connector)
5. End with the End terminator, typically on the right side
6. Identify notes or business rules from the requirements that should be annotation boxes

Phase 4: Build the Lucid Standard Import JSON

Read references/lucid-spec-format.md for the exact JSON format and Python generator pattern.

This is the critical step. You must generate a Python script that outputs the Standard Import JSON specification, then execute it to produce the JSON, then pass that JSON to the Lucid MCP tool.

The approach:

1. Write a Python script using the proven helper functions (see references/lucid-spec-format.md)
2. Adapt the color palette, swimlane labels, legend entries, and title to the specific project
3. Position shapes on a coordinate grid — see the positioning guide in the reference
4. Execute the script to produce the JSON spec
5. Pass the JSON to lucid_create_diagram_from_specification

Phase 5: Create the Diagram in Lucid

1. Create the diagram using lucid_create_diagram_from_specification with the full Standard Import JSON spec.
   • The specification parameter accepts the JSON as a string.
   • Always include "version": 1 at the top level.
2. Name the diagram following the convention: [Project]_[ProcessName]_ProcessFlowDiagram
3. Get the share link using lucid_create_document_share_link.

Phase 6: Confirm with User

Present:

• The Lucid diagram link
• A text summary of the flow steps and decision points
• A count of shapes and lines (for complexity reference)
• Ask if any adjustments are needed

Visual Standards

These are the default professional visual standards. They can be customized per project, but start with these:

1. Always use swimlanes — minimum two horizontal lanes
2. Five shape types only — Terminator, Data (I/O), Manual Input, Decision, Process
3. Color consistency — within each diagram, the same shape type always uses the same color
4. White text inside all colored shapes
5. Title banner spanning the full width at the top (dark green by default)
6. Legend block at bottom-left showing system/application color mapping
7. Yes/No labels on all decision branch connectors
8. Notes as annotation boxes — light blue background, attached to relevant shapes
9. Left-to-right flow within each swimlane
10. Vertical connectors when crossing between swimlanes

Default Color Palette

Title Banner:     #1E5631 (dark green), white uppercase text
Terminator:       #1B4F6B (navy), white text — "Start" / "End"
Manual Input:     #E8A838 (gold), white text — user actions
Data (I/O):       #2E86AB (teal), white text — system displays
Decision:         #E8A838 (gold), white text — Yes/No branches
Process:          #2E86AB (teal), white text — system automation
Connectors:       #333333 (dark gray), solid lines with arrowheads
Swimlane fill:    #F5F5F5 (light gray) for actor lanes, #FFFFFF for system lanes
Note boxes:       #D6EAF8 fill, #85C1E9 border, #333333 text

These colors can be swapped for project-specific branding. The key principle is: human actions get one color (gold), system actions get another (teal), and terminators get a third (navy). This three-color distinction is what makes the diagram instantly readable.

Adapting for Different Projects

This skill is not tied to any specific project. When adapting:

1. Change the title banner text to the project/system name
2. Update swimlane labels to match the actors and systems involved
3. Update the legend to show the relevant systems/applications
4. Adjust colors if the project has brand guidelines (but maintain the human-vs-system color distinction)
5. Scale the canvas based on flow complexity:
   • Simple flow (5-10 shapes): 1200px wide
   • Medium flow (10-20 shapes): 1800-2200px wide
   • Complex flow with branches (20+ shapes): 2500-3000px wide

Example Adaptations

Handling Edge Cases

• Multiple sub-processes in one diagram: Use decision diamonds to route between branches (Create → Modify → Delete → Enable/Disable pattern).
• Large diagrams (25+ shapes): Suggest splitting into multiple pages/documents. Each page should be a self-contained sub-flow.
• Ambiguous actor/system assignments: Default to the most common pattern, flag the ambiguity, and ask.
• Missing details: If requirements are vague about step ordering or branching, propose the most logical flow and confirm.
• Multi-page diagrams: The Lucid API creates a new document per call. For multi-page diagrams, create separate documents and note the limitation.

Quick Reference

Shapes:    terminator | manualInput | data | decision | process
Colors:    Navy #1B4F6B | Gold #E8A838 | Teal #2E86AB | Green #1E5631
Format:    Standard Import JSON, version 1
BBox:      {x, y, w, h}  — NOT width/height
Swimlanes: vertical: false, lane "width" = row HEIGHT
Lines:     lineType: "elbow", shapeEndpoint with arrow style
Tool:      lucid_create_diagram_from_specification
Naming:    [Project]_[Process]_ProcessFlowDiagram