What to capture before you configure a workflow

Whenever a business sets up a new approval workflow, routing rule, or automated process, someone has to sit down and specify exactly what should happen at each step. That's already work being done. What almost never happens at the same time, despite costing almost nothing extra, is capturing why each step is the way it is — and that omission is what makes the workflow hard to question or improve later.

Why this moment is uniquely cheap

At the point of configuration, the reasoning is fully available and already being actively discussed. Someone is deciding that invoices over a certain amount need a second approver — right then, they know why that threshold, not a different one. They're deciding that certain suppliers skip a step — right then, they know which suppliers and why.

Six months later, someone looking at the same workflow has none of that context readily available. Reconstructing it means finding whoever configured it, hoping they remember, and hoping their memory is accurate — see institutional memory has a shelf life. Capturing it at the time costs a few extra sentences during a conversation that's already happening. Reconstructing it later costs an investigation that might not even succeed.

What specifically to write down

The threshold and why that number. Not just "orders over RM5,000 need approval" but why that particular figure — is it based on a materiality assessment, a past incident, a rough estimate that seemed reasonable at the time? Each of these implies something different about whether the threshold should change later.

Who's exempted, and why. Workflows often carve out exceptions for specific suppliers, customers, or departments. Recording why a particular exemption exists prevents it from looking arbitrary to whoever reviews the workflow next — see configuration without a reason attached.

What problem the workflow was designed to prevent. A workflow built in response to a specific past incident makes far more sense to a future reviewer once they know the incident existed, even in a single sentence, than it does as an isolated rule with no visible purpose.

Why this is different from documenting the workflow itself

Most businesses do document what a workflow does — the steps, the routing logic, the approvers. That's necessary and usually already happens, because someone has to configure the actual settings regardless. What's missing is the layer underneath: not what the workflow does, but why it does it that way rather than some other reasonable way. The what is mechanical and self-evident from looking at the configuration. The why is exactly the part that disappears the moment the person who built it moves on.

A practical habit for anyone configuring a new workflow

Add a short "reasoning" note as a required part of setting up any new workflow, alongside the technical configuration — not a separate document, attached directly to the workflow itself where anyone reviewing it later will actually see it.

Write it for someone who wasn't in the room, the same discipline that makes any captured reasoning useful — assume the reader has no context beyond what's in front of them, and write accordingly.

Revisit it when the workflow is reviewed, not just when it's built. If a workflow is later modified, that's the moment to check whether the original reasoning still applies, or whether the change is happening precisely because the original reasoning no longer holds.

Why this compounds over time

A business that captures reasoning at every workflow's creation builds, without any extra dedicated effort, a genuinely useful record of why its processes look the way they do. A business that doesn't accumulates workflows that work but can't be explained, reviewed with confidence, or safely simplified — because nobody can tell which parts are load-bearing and which are historical accidents nobody's gotten around to removing.

Common questions

Why is the moment of configuring a workflow the best time to capture its reasoning?

Because at that point, whoever is setting it up already has full access to the reasoning and is actively articulating the steps anyway. Capturing the why alongside the what costs a few extra sentences. Reconstructing it later, once the person has moved on, requires an investigation that may not even succeed.

What details are most important to capture when setting up a workflow?

The specific reasoning behind any threshold or number used, which suppliers, customers or cases are exempted and why, and what problem — often a specific past incident — the workflow was originally designed to prevent. These are exactly the details that look arbitrary to a future reviewer without the original context.

How is this different from documenting what a workflow does?

Documenting what a workflow does covers the steps and routing logic, which is mechanical and usually already captured because someone has to configure it regardless. Documenting why covers the reasoning behind those choices, which is a separate layer that disappears the moment the person who built it moves on, unless it's deliberately written down at the time.

What happens to a business that never captures this reasoning?

It accumulates workflows that function correctly but can't be explained, safely modified, or confidently simplified, because nobody can distinguish which parts of the configuration are genuinely load-bearing and which are historical artefacts nobody has gotten around to questioning.

Related: configuration without a reason attached · institutional memory has a shelf life · why it has always been done this way survives automation