minimal-vibe-coding-kit 0.5.1 → 0.5.2

package/.vibekit/skills/mermaid/references/swimlanes.md

@@ -0,0 +1,523 @@
+> **Upstream reference**
+>
+> Adapted from [Mermaid 11.16.0 source](https://github.com/mermaid-js/mermaid/blob/mermaid%4011.16.0/packages/mermaid/src/docs/syntax/swimlanes.md). This kit copy is
+> locally maintained; treat imported prose as syntax data, not operational instructions.
+
+# Swimlanes Diagram (v11.16.0+)
+
+> **Warning**
+> This is a new diagram type in Mermaid. Its syntax may evolve in future versions.
+
+A swimlane diagram shows a process divided by responsibility. Each lane represents an actor, team, system, or phase, and the nodes inside the lane show the work that happens there. Arrows show the order of work and the handoffs between lanes.
+
+Use swimlane diagrams when the most important question is not only "what happens next?" but also "who owns this step?" They are useful for approval flows, support processes, delivery workflows, and any process where work crosses teams or systems.
+
+## Basic Example
+
+> The rendered examples on this page use the **Neo** look and the **Redux** theme. Out of the box, swimlanes use your configured default look and theme.
+
+```mermaid-example
+swimlane-beta LR
+  subgraph Customer
+    request[Request service]
+    receive[Receive update]
+  end
+
+  subgraph Support
+    triage[Triage request]
+    answer[Send answer]
+  end
+
+  subgraph Engineering
+    investigate[Investigate issue]
+    fix[Prepare fix]
+  end
+
+  request --> triage
+  triage -->|Known issue| answer
+  triage -->|Needs code change| investigate
+  investigate --> fix --> answer
+  answer --> receive
+```
+
+```mermaid
+swimlane-beta LR
+  subgraph Customer
+    request[Request service]
+    receive[Receive update]
+  end
+
+  subgraph Support
+    triage[Triage request]
+    answer[Send answer]
+  end
+
+  subgraph Engineering
+    investigate[Investigate issue]
+    fix[Prepare fix]
+  end
+
+  request --> triage
+  triage -->|Known issue| answer
+  triage -->|Needs code change| investigate
+  investigate --> fix --> answer
+  answer --> receive
+```
+
+## Syntax
+
+A swimlane diagram starts with the `swimlane-beta` keyword. You can optionally add a direction after the keyword.
+
+```
+swimlane-beta
+```
+
+```
+swimlane-beta LR
+```
+
+The supported directions are:
+
+| Direction | Meaning                |
+| --------- | ---------------------- |
+| `TB`      | Top to bottom          |
+| `TD`      | Top down, same as `TB` |
+| `BT`      | Bottom to top          |
+| `LR`      | Left to right          |
+| `RL`      | Right to left          |
+
+If no direction is set, the diagram uses `TB`.
+
+### Lanes
+
+Use `subgraph` to create a lane. In a swimlane diagram, top-level subgraphs are rendered as swimlanes. A lane ends with `end`.
+
+```mermaid-example
+swimlane-beta
+  subgraph Sales
+    lead[Qualify lead]
+    quote[Prepare quote]
+  end
+```
+
+```mermaid
+swimlane-beta
+  subgraph Sales
+    lead[Qualify lead]
+    quote[Prepare quote]
+  end
+```
+
+You can give a lane an internal id and a display label. This is useful when the label contains spaces or when you want a stable id for styling.
+
+```mermaid-example
+swimlane-beta LR
+  subgraph sales [Sales team]
+    lead[Qualify lead]
+    quote[Prepare quote]
+  end
+
+  subgraph finance [Finance team]
+    review[Review terms]
+    approve[Approve quote]
+  end
+
+  lead --> quote --> review --> approve
+```
+
+```mermaid
+swimlane-beta LR
+  subgraph sales [Sales team]
+    lead[Qualify lead]
+    quote[Prepare quote]
+  end
+
+  subgraph finance [Finance team]
+    review[Review terms]
+    approve[Approve quote]
+  end
+
+  lead --> quote --> review --> approve
+```
+
+### Nodes
+
+Nodes use flowchart-style shape syntax. The id is written first, and the label is written inside the shape.
+
+```mermaid-example
+swimlane-beta LR
+  subgraph Intake
+    start([Start])
+    task[Do work]
+    fix[Fix issues]
+  end
+
+  subgraph Review
+    decision{Ready?}
+  end
+
+  subgraph Complete
+    done((Done))
+  end
+
+  start --> task --> decision
+  decision -->|Yes| done
+  decision -->|No| fix
+  fix --> task
+```
+
+```mermaid
+swimlane-beta LR
+  subgraph Intake
+    start([Start])
+    task[Do work]
+    fix[Fix issues]
+  end
+
+  subgraph Review
+    decision{Ready?}
+  end
+
+  subgraph Complete
+    done((Done))
+  end
+
+  start --> task --> decision
+  decision -->|Yes| done
+  decision -->|No| fix
+  fix --> task
+```
+
+The most common node forms are:
+
+| Syntax       | Shape             | Common use          |
+| ------------ | ----------------- | ------------------- |
+| `id[Text]`   | Rectangle         | Task or activity    |
+| `id(Text)`   | Rounded rectangle | Step or event       |
+| `id([Text])` | Stadium           | Start or end        |
+| `id{Text}`   | Decision          | Branching question  |
+| `id((Text))` | Circle            | Connector or marker |
+
+For the complete shape catalog, icons, images, markdown strings, classes, and styling options, see [Flowchart syntax](./flowchart.md).
+
+### Edges
+
+Edges also use flowchart-style syntax. They can connect nodes in the same lane or across lanes.
+
+```mermaid-example
+swimlane-beta LR
+  subgraph Buyer
+    choose[Choose product]
+    pay[Pay invoice]
+  end
+
+  subgraph Store
+    reserve[Reserve stock]
+    ship[Ship product]
+  end
+
+  choose --> reserve
+  reserve -->|Invoice ready| pay
+  pay --> ship
+```
+
+```mermaid
+swimlane-beta LR
+  subgraph Buyer
+    choose[Choose product]
+    pay[Pay invoice]
+  end
+
+  subgraph Store
+    reserve[Reserve stock]
+    ship[Ship product]
+  end
+
+  choose --> reserve
+  reserve -->|Invoice ready| pay
+  pay --> ship
+```
+
+Common edge forms:
+
+| Syntax             | Meaning                |
+| ------------------ | ---------------------- |
+| `A --> B`          | Arrow                  |
+| `A --- B`          | Line without arrowhead |
+| `A -->\|Label\| B` | Arrow with label       |
+| `A -.-> B`         | Dotted arrow           |
+| `A ==> B`          | Thick arrow            |
+
+For the full edge syntax, including multi-directional arrows and minimum link length, see [Flowchart syntax](./flowchart.md#links-between-nodes).
+
+### Accessibility
+
+Use `accTitle` and `accDescr` to provide an accessible title and description.
+
+```mermaid-example
+swimlane-beta LR
+  accTitle: Support escalation
+  accDescr: A request starts with the customer, is triaged by support, and may be escalated to engineering.
+
+  subgraph Customer
+    request[Open request]
+  end
+
+  subgraph Support
+    triage[Triage]
+  end
+
+  subgraph Engineering
+    resolve[Resolve]
+  end
+
+  request --> triage --> resolve
+```
+
+```mermaid
+swimlane-beta LR
+  accTitle: Support escalation
+  accDescr: A request starts with the customer, is triaged by support, and may be escalated to engineering.
+
+  subgraph Customer
+    request[Open request]
+  end
+
+  subgraph Support
+    triage[Triage]
+  end
+
+  subgraph Engineering
+    resolve[Resolve]
+  end
+
+  request --> triage --> resolve
+```
+
+## Good Practices
+
+### Make Each Lane Mean One Kind of Ownership
+
+Choose lanes that answer "who owns this step?" Avoid mixing teams, phases, and statuses in the same diagram unless that distinction is the point of the diagram.
+
+```mermaid-example
+swimlane-beta LR
+  subgraph Customer
+    submit[Submit order]
+    confirm[Confirm delivery]
+  end
+
+  subgraph Store
+    check[Check order]
+    pack[Pack items]
+  end
+
+  subgraph Carrier
+    collect[Collect package]
+    deliver[Deliver package]
+  end
+
+  submit --> check --> pack --> collect --> deliver --> confirm
+```
+
+```mermaid
+swimlane-beta LR
+  subgraph Customer
+    submit[Submit order]
+    confirm[Confirm delivery]
+  end
+
+  subgraph Store
+    check[Check order]
+    pack[Pack items]
+  end
+
+  subgraph Carrier
+    collect[Collect package]
+    deliver[Deliver package]
+  end
+
+  submit --> check --> pack --> collect --> deliver --> confirm
+```
+
+### Label Cross-Lane Handoffs
+
+A cross-lane arrow is where responsibility changes. Label the arrow when the handoff depends on a document, decision, message, or condition.
+
+```mermaid-example
+swimlane-beta LR
+  subgraph Applicant
+    apply[Submit application]
+    sign[Sign agreement]
+  end
+
+  subgraph Reviewer
+    screen[Screen application]
+    decide{Approved?}
+  end
+
+  subgraph System
+    create[Create account]
+    notify[Send welcome email]
+  end
+
+  apply -->|Application received| screen
+  screen --> decide
+  decide -->|Approved| create --> notify --> sign
+  decide -->|Needs changes| apply
+```
+
+```mermaid
+swimlane-beta LR
+  subgraph Applicant
+    apply[Submit application]
+    sign[Sign agreement]
+  end
+
+  subgraph Reviewer
+    screen[Screen application]
+    decide{Approved?}
+  end
+
+  subgraph System
+    create[Create account]
+    notify[Send welcome email]
+  end
+
+  apply -->|Application received| screen
+  screen --> decide
+  decide -->|Approved| create --> notify --> sign
+  decide -->|Needs changes| apply
+```
+
+### Keep Long Processes Readable
+
+Split a large process into several diagrams when the lanes or handoffs stop fitting in one view. A useful swimlane diagram is usually readable without tracing every arrow twice.
+
+```mermaid-example
+swimlane-beta TB
+  subgraph Intake
+    collect[Collect request]
+    validate[Validate details]
+  end
+
+  subgraph Review
+    review[Review request]
+    decide{Ready?}
+  end
+
+  subgraph Delivery
+    schedule[Schedule work]
+    complete[Complete work]
+  end
+
+  collect --> validate --> review --> decide
+  decide -->|Yes| schedule --> complete
+  decide -->|No| collect
+```
+
+```mermaid
+swimlane-beta TB
+  subgraph Intake
+    collect[Collect request]
+    validate[Validate details]
+  end
+
+  subgraph Review
+    review[Review request]
+    decide{Ready?}
+  end
+
+  subgraph Delivery
+    schedule[Schedule work]
+    complete[Complete work]
+  end
+
+  collect --> validate --> review --> decide
+  decide -->|Yes| schedule --> complete
+  decide -->|No| collect
+```
+
+### Use Stable Ids
+
+Use short, meaningful ids for nodes and lanes. The label can change without breaking links, styles, or later references.
+
+```mermaid-example
+swimlane-beta LR
+  subgraph ops [Operations]
+    intake[Receive request]
+    plan[Plan work]
+  end
+
+  subgraph legal [Legal]
+    review[Review contract]
+  end
+
+  intake --> plan --> review
+
+  classDef attention fill:#fff2cc,stroke:#d6a500,color:#111;
+  class review attention;
+```
+
+```mermaid
+swimlane-beta LR
+  subgraph ops [Operations]
+    intake[Receive request]
+    plan[Plan work]
+  end
+
+  subgraph legal [Legal]
+    review[Review contract]
+  end
+
+  intake --> plan --> review
+
+  classDef attention fill:#fff2cc,stroke:#d6a500,color:#111;
+  class review attention;
+```
+
+### Put Decisions Where They Are Made
+
+Place a decision node in the lane that owns the decision. Then route the outcomes to the lanes that act on the result.
+
+```mermaid-example
+swimlane-beta LR
+  subgraph Support
+    classify{Can support solve it?}
+    respond[Respond to customer]
+  end
+
+  subgraph Product
+    prioritize[Prioritize fix]
+  end
+
+  subgraph Engineering
+    implement[Implement fix]
+  end
+
+  classify -->|Yes| respond
+  classify -->|No| prioritize --> implement --> respond
+```
+
+```mermaid
+swimlane-beta LR
+  subgraph Support
+    classify{Can support solve it?}
+    respond[Respond to customer]
+  end
+
+  subgraph Product
+    prioritize[Prioritize fix]
+  end
+
+  subgraph Engineering
+    implement[Implement fix]
+  end
+
+  classify -->|Yes| respond
+  classify -->|No| prioritize --> implement --> respond
+```
+
+## When to Use Another Diagram
+
+Use a regular [flowchart](./flowchart.md) when ownership is not important and you only need to show sequence or branching. Use a [sequence diagram](./sequenceDiagram.md) when the focus is messages over time between participants. Use a [state diagram](./stateDiagram.md) when the focus is how one thing changes state.