SKILL.md
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.