Requirement diagrams

TL;DR

Ask your agent

Name each requirement with its id, say how risky it is and how it is proved, then name the code, tests, and documents that meet it.

Use Plotwork to draw a requirement diagram of our checkout. REQ-001: the checkout accepts Visa, Mastercard and Amex; it is functional, high risk, and proved by test. REQ-002: a payment completes in under two seconds at the 95th percentile; performance, medium risk, tested. REQ-003: card data never touches our servers; a design constraint, high risk, proved by inspection, and it refines REQ-001. Stripe Elements satisfies REQ-001 and REQ-003, the end-to-end suite verifies REQ-001 and REQ-002, and the PCI self-assessment verifies REQ-003.

Use Plotwork to draw the hardware requirements of our drone flight controller, reading left to right: it weighs under 40 g and fits a 30.5 mm mount (physical), talks CAN and UART (interface, high risk), and runs its control loop at 8 kHz (performance, proved by analysis). The board satisfies the weight and the mount, the STM32H7 satisfies the bus and the loop, the bench rig verifies the bus and the weight, and the timing model verifies the loop.

Use Plotwork to draw the traceability of our account security. The business requirement BR-1, accounts are hard to take over, is high risk and contains SR-1, offer a second factor, and SR-2, lock out repeated failures. SR-1 derives from BR-1. The auth design note traces to SR-1 and SR-2, the auth test suite verifies both, and the annual penetration test verifies BR-1.

Example

This is the checkout from the first prompt. Three requirements sit at the top, the constraint that refines the first sits below it, and the elements that satisfy and verify them sit at the bottom. Every line carries its word, and every requirement carries its risk and how it is verified.

PictureSourceOutline

A hardware specification

Physical and interface requirements, each met by a part and proved by a rig or a model. Eight cards side by side would be too wide for a column, so direction=right stacks the requirements on the left and the parts and tests on the right.

PictureSourceOutline

A traceability chain

A business requirement broken down into system requirements with contains, which starts with a circled plus at the container, and the derived relations drawn dashed. The high-risk business requirement is verified by a test of its own, so nothing is left unproved.

PictureSourceOutline

The language

A line is one statement. A # starts a comment. Ids are words such as card, req-1 or _x, labels are in double quotes, and options are written key=value. The first line is the header.

The header

requirement "Checkout requirements" direction=down desc="What the checkout must do, and what proves it."

Statements

The statement is need, not requirement, because requirement is the header. A Mermaid block such as functionalRequirement x { is an error whose hint shows the line to write.

Requirement types

tone= overrides the type's tone. A diagram cannot set a color: the theme chooses every color, in light and dark.

Risk and verification

risk= is low, medium, or high, drawn as a chip with a green, amber, or red dot. verify= is analysis, inspection, test, or demonstration, drawn as a chip with its icon. The chips sit at the foot of the card, and the words say the same as the colors, so the diagram still reads for someone who cannot tell two tones apart.

ref= is the id people use, such as REQ-001, drawn on the right of the strip. Quote it, since it often holds a -. text= is the requirement sentence, wrapped in the card; past five lines it is cut with warning W203, and the full sentence stays in the text description.

Relations

A relation reads from left to right as a sentence: stripe -> card : satisfies is "Stripe Elements satisfies Accept card payments". The layout puts what is required above what relates to it, so most arrows point up, at the requirement.

Every relation draws its word in a pill on the line, next to the card below. Lines run through the gaps between ranks and never through a card.

Limits and warnings

Warnings never stop a diagram from being drawn. Errors do.

Layout is plain arithmetic, so even a diagram at the limits is laid out in a few milliseconds.

From Mermaid

Mermaid's requirementDiagram converts with convert_mermaid. The fields of each block become options on one line, and a relation written either way round becomes one -> line.

Mermaid draws a requirement's name as its title, so the converter keeps the name as the label. Rename the labels to the words people use, and check in the outline that each relation reads the right way round.

See also