Automation Without Losing the Plot

The first version of an automation usually has a clear plot. Something arrives, a few rules are applied, a result is sent somewhere useful. The person building it can draw the whole thing on paper because the problem is still small enough to fit inside one explanation.

Then the exceptions arrive. A second source uses different field names. One client needs a separate approval. A failure that was harmless on Tuesday becomes expensive on Friday, so a retry is added. Six months later, the simple flow has become a small private institution whose rules are known mainly through incidents.

This is where teams make an understandable mistake. They treat legibility as documentation work to be completed after the automation is finished. By then the system is already running, the builder has moved on and nobody wants to touch the part that appears to work. The missing explanation becomes somebody else's future problem.

If nobody can explain how an automated process reaches a consequential decision, the process is not finished. It may be fast. It may be reliable under current conditions. It is still carrying operational debt.

Legibility is part of the system

An understandable automation exposes four things without requiring an archaeological dig: what starts it, what information it changes, where a human can intervene and what happens when it fails. These are basic questions, but many production workflows answer them only by making somebody open five tools and follow a trail of identifiers across each one.

The usual defence is that the underlying logic is obvious from the implementation. That is true only to the person currently holding the whole implementation in their head. Code can describe each local operation accurately while leaving the reason for the overall sequence completely obscure. A filter says which records pass; it does not say why the business decided those records should pass, or who is allowed to change that decision.

The same problem appears in no-code systems, where visual blocks create an impression of transparency. A flowchart with forty nodes is not automatically understandable because the lines are visible. It may be harder to review than code, especially when the important behaviour is hidden inside configuration panels, copied formulas and credentials owned by one person's account.

Before an automation goes live, someone other than its builder should be able to answer:

• What event starts this process, and can it start twice?
• Which source is authoritative when two inputs disagree?
• What decisions are rules, and which are model-generated judgments?
• Where does a person approve, correct or stop the result?
• What is recorded when the process succeeds or fails?
• Who receives the failure, and what can they safely do next?
• How can the system be disabled without losing the work already in flight?

That list is not governance theatre. It is a practical test of whether the automation belongs to the team or merely happens to be running near it.

Put the explanation beside the behaviour

Documentation decays fastest when it lives far from the thing it describes. A diagram in a presentation becomes inaccurate after one quiet change to a branch. A runbook in a shared folder survives until the folder is reorganised. The more consequential parts of the explanation should therefore sit as close as possible to the behaviour: clear names in the flow, short comments around non-obvious rules, versioned configuration and an audit trail written for a person rather than only for a debugger.

Consider a publishing automation that releases an approved issue. The interesting part is not the call that renders a page. It is the boundary that prevents an unapproved draft from being published and the record that explains what happened afterwards.

async function publishIssue(issueId) {
    const issue = await loadIssue(issueId);

    if (!issue.approvedAt) {
        throw new Error("Publication stopped: editorial approval is missing");
    }

    const result = await renderIssue(issue);

    await auditLog.write({
        action: "issue.published",
        issueId,
        approvedAt: issue.approvedAt,
        outputId: result.id
    });

    return result;
}

This example is deliberately plain. It names the condition that matters, stops rather than guessing and records enough context for the next person to reconstruct the event. A production system would need more around it, but more should not mean that the central rule becomes harder to see.

AI-assisted steps make this discipline more important, not less. A model can classify, summarise or propose an action without exposing a stable chain of reasoning. The surrounding system must compensate by recording the input version, the output, the rule that permitted the output to continue and the point at which a human can reject it. “The model decided” is not a useful operational explanation.

Teams sometimes resist this because the additional checks appear to slow down the very process automation was meant to accelerate. That is a narrow measurement. The time saved in normal operation is only one part of the cost. The time required to investigate an error, transfer ownership or rebuild lost context belongs in the same calculation.

Recovery is the real test

Most automation demonstrations follow the happy path. A clean input arrives, every service responds and the output appears on cue. The harder and more revealing demonstration begins with a failure halfway through. Can the team tell what completed? Can it safely run the process again? Will a retry create a duplicate invoice, message or publication? Does the failure reach someone who understands its consequence?

Recovery exposes the difference between a useful shortcut and a system the organisation can depend on. It also exposes hidden ownership. If only the original builder can decide whether a failed run is safe to retry, that person has not automated the process so much as moved their involvement to unpredictable moments.

The remedy is not to build an elaborate control room around every small workflow. Proportion still matters. An automation that renames internal files can fail less gracefully than one that sends client communication or changes financial records. What matters is making the consequence explicit and matching the safeguards to it.

Good automation removes repetitive effort while preserving understanding. It gives the team fewer steps to perform, not fewer ways to know what is happening. The distinction can look pedantic while everything works. The moment it does not, it becomes the whole plot.