diagramming-processes

The saved excerpt is a snapshot from when this skill was listed. The external source remains the complete and most current version.

---
name: diagramming-processes
description: Use when a business process, workflow, lifecycle, or interaction between systems needs a diagram - a flow that prose serializes badly, a state machine, a message sequence, an enterprise process map - or when drawing the process documentation of a legacy campaign. Encodes diagrams-as-source, the notation ladder from ArchiMate to PlantUML, the kind-per-question table, behavior-level participants, the diagram index, and the same-change maintenance rule. Use whenever a document needs a graph rather than more paragraphs, even if nobody says "PlantUML".
---

# Diagramming processes

**REQUIRED BACKGROUND:** the `technical-writing` skill (hard rules, truth rules, style).

## Overview

A diagram is a set of claims drawn instead of written; every box and arrow is bound by the same truth rules as a sentence. Core principle: **diagram the behavior (processes, lifecycles, interactions), keep the source in version control, and treat every render as derived.** The prose owns the reasoning; the diagram carries what prose serializes badly: branching, concurrency, and state.

## When to invoke, and not

Invoke when a flow, lifecycle, or interaction needs showing: a business process spanning components or organizations, a state machine, a message exchange, the `processes.md` of a legacy campaign (`documenting-legacy-codebases`). Do NOT invoke to decorate: a linear flow of three or four steps is a numbered list, and a diagram restating one is furniture. Out of scope: charts generated from data (metrics, trends), and implementation structure, which the behavior rule below forbids.

## The notation ladder

Name the altitude before drawing, and match the notation to it:

- **Business layer: ArchiMate.** Processes spanning departments, organizations, or multiple systems, capability maps, and the TOGAF-style views enterprise stakeholders expect. The audience reads roles, services, and processes, never components.
- **System layer: PlantUML behavior diagrams.** Flows, state machines, and sequences within and between systems: code documentation, one level above the code.
- **Code layer: no diagrams.** Class and package structure is the code's own to show; an IDE generates a fresher picture on demand than any committed one.

The ladder sets the notation and the vocabulary, never the tool: one toolchain can serve both rungs, because PlantUML carries the ArchiMate notation in its standard library. The tool a repository uses is settled once, under "Source, not pictures".

## Source, not pictures

- The source is committed text, in the diagram tool the repository already uses. Where none is established, PlantUML is the default (rich standard library, ArchiMate included); where the choice is genuinely open, ask the owner, recommending PlantUML. The core skill's `references/truth.md` owns the ground rule: rendered output is derived, and stale renders are deleted rather than left to mislead.
- One diagram per source file, named for the process it shows, grouped in one diagrams directory beside the documents.
- Rendering requires tooling the repository owns (a script, a make target, or a build step), set up by the owner, not by the diagram's author. Tell the owner when it is missing; never route around the gap by picking whatever notation the hosting platform happens to render inline.
- One repo command renders everything; renders are committed unless the host already renders the repository's chosen source format. When a source changes, its outdated render is deleted in the same change, and the missing render is recorded in the index until regenerated.
- A screenshot, an exported picture, or a whiteboard photo with no source is a finding against the document that contains it: nobody can diff it, so nobody will maintain it.

## The kind answers the reader's question

Pick the kind from the question the reader brings, one question per diagram:

| The reader asks | Draw |
|---|---|
| How does this process run across the