Controls Matrix

Overview

Individual findings tell you about one specific pattern in one specific place. The Controls Matrix asks a broader question first: across the whole workflow, which categories of protection exist at all? It's a fixed checklist of nine controls, always in the same order, always covering the same ground, so a matrix from one workflow can be compared directly against a matrix from another.

It exists because "how many findings does this have" is a noisy way to judge safety posture. A workflow with three findings, all pointing at the same missing control, is in a very different position than one with three findings each pointing at a different missing control. The matrix makes that visible at a glance, before reading a single finding description.

What question it answers

"Which categories of protection does this workflow have, and which does it not?" Not what specifically is wrong — that's still the findings list — but if the workflow's safety net had to be described in nine yes/no/partial answers, what would they be?

How to read it

Nine controls, always in this order, each with a status.

Control	What it checks	Impact if missing
Error workflow	Is an error workflow attached?	Failures are silent — visible only in the execution log
External retries	Do external calls retry on failure?	Transient failures cause permanent stops
Timeouts	Do external calls have timeouts?	A slow provider can block execution indefinitely
Idempotency guard	Is there a guard in front of writes to prevent duplicates?	Retrying on a write event creates duplicate records
Empty-state branch	Do conditional branches have a default/empty-result path?	A zero-result lookup breaks downstream logic
AI token cap	Is there a token/output limit on AI calls?	Output cost and parsing risk are unbounded
Structured AI output	Is AI output parsed into a structured format before use?	Free-form output will break downstream parsers
Audit log	Is there a log of consequential writes?	Side effects go unlogged
Dedup before write	Is there de-duplication before a write?	Webhook replays can create duplicate records

Each control lands in one of four states:

• present — the pattern is implemented.
• partial — implemented for some but not all of the relevant paths; a detail field explains which ones are missing it.
• missing — not implemented anywhere it applies.
• n/a — the control doesn't apply to this workflow. A workflow with no writes doesn't need a dedupe guard.

Every control also lists the finding rule IDs it maps to — a missing status isn't a separate judgment call, it's a direct reflection of what the findings engine already detected.

Example: idempotency_guard: partial, detail: "3 of 5 write operations have a guard." Two writes are exposed to duplication on retry; the other three are covered. That's a materially different situation from missing — none covered — and worth fixing at the two specific nodes rather than assuming the whole workflow needs the same treatment.

How to decide what to do

Read the matrix as a triage list before the findings list, not instead of it.

1. Scan for missing first — these are gaps with no mitigation anywhere in the workflow, and the fastest way to see the biggest structural holes.
2. Check partial next — these usually mean the fix pattern is already used somewhere in the workflow, so the fastest remedy is copying that pattern to the uncovered paths rather than designing something new.
3. Cross-reference against the Executive Summary — a missing idempotency guard next to a financial write is exactly the combination that triggers the hard score cap described in the Overview article, so treat that specific pairing as higher priority than the matrix status alone suggests.
4. Don't chase n/a — it means the control doesn't apply, not that something was skipped.

Related reading

• Overview — how the nine controls map onto category scores and the hard score caps
• Reliability — most of these controls originate here
• Break Points — the ranked findings behind a missing or partial status