From Complaint to Spec: How an Automation Brief Gets Written
Every automation starts as a complaint, and a complaint is not a specification. 'This process is broken' contains no inputs, no rules, no outputs, and no…
Every automation project begins with a complaint. Somebody says the process is broken, or the team is drowning, or this takes far too long. The complaint is real and it is usually accurate. The complaint is not a specification. It contains no inputs, no rules, no outputs, and no description of what happens when the rules do not apply. Between the complaint and the build there is a translation step, and that step is a distinct skill that looks nothing like writing. It is interrogation. It is also the step that most often gets skipped, which is why so many systems deliver exactly what was asked for and nothing that was needed. Take the onboarding engagement. Applications waited in a manual review queue. A dedicated review team reviewed them manually. Everyone involved was competent and everyone was overwhelmed. Stated as a complaint, that situation comes out like this: onboarding takes too long and the team is drowning. Every word of it is true. None of it is buildable. The complaint is a symptom report, and a symptom report tells you where it hurts, not what is wrong. Read the sentence again for what it does not contain. It does not tell you which step consumes the time, whether that is classification, cross-referencing, exception flagging, or the wait between handoffs. It does not tell you which decisions are actually being made, or on what basis, or by whom. Nothing in it covers the submissions that do not fit the normal shape, which is usually where the most senior attention quietly goes. Build from the complaint and you get a faster version of a process nobody has described. That defect sits at the root of most automation that disappoints. The first question is what enters the workflow, and in what form. Not what the input is called, what it actually looks like when it arrives. In the onboarding case the inputs were submitted documents arriving in varying formats and the historical record those documents were scored against, fourteen months of prior adjudication decisions. The mistake people make here is naming the input and stopping. Applications is a name. A specification needs the shape: which formats arrive, how often they are incomplete, which fields appear in every submission and which appear in half of them. If you cannot describe the input at that resolution, you are guessing at the parser, and you find out you guessed wrong once real volume reaches it. The second question is what decision is being made, and on what basis. This one takes the longest, because the answer lives in someone's head and has never been said out loud. The reviewer knows an application is clean. Ask them why and you get a policy: we check the documents against the record and flag discrepancies. That policy is not what they do. It is what they believe they do. The technique that works is to stop asking about the policy and walk through the last ten cases file by file, asking what happened and why. People describe their policy accurately and their behavior inaccurately. The specification has to encode the behavior, because the behavior produced the outcomes the system will be scored against. The third question is what leaves the workflow. A decision, a record written somewhere, a notification sent to someone, a trigger fired into a downstream system. Most briefs stop at the decision and treat the rest as implementation detail, which is how you end up with a system that classifies correctly and updates nothing. Being specific here is what makes the system testable. A decision is an opinion. A decision plus a written record plus a notification plus a downstream call is a set of assertions you can check on day one. If you cannot write the test before the build starts, the output is not specified yet. The fourth question is what happens when the rules do not apply. Skipping it is the single most common cause of a system that works in the demo and fails in production. Demos run on the cases the rules were written for. Production runs on everything else as well. In the onboarding system the exception path is a first-class part of the design: cases that fall outside the confidence threshold reach a human with the extracted data, the confidence score, and the reason for the uncertainty already assembled. Specify that path in the brief and you get a path. Leave it implied and you get an inbox, with escalations arriving stripped of the context that would let anyone act on them. Trigger. What starts the workflow, stated as an event rather than a schedule wherever possible. A document lands in the intake queue is a trigger. Every morning at nine is a workaround for not knowing the trigger. Inputs. Every piece of data the workflow reads, with its format, its source system, and its expected completeness. The mistake is listing the happy-path fields and omitting the ones that arrive empty half the time. Decision rules. The logic in condition-and-consequence form, written at the resolution of the last ten cases rather than the stated policy. If a rule cannot be written as a condition and a consequence, it is not a rule yet. It is a preference, and it needs another round of questions. Confidence threshold. The line above which the system acts alone and below which it escalates, expressed as a number with a stated reason. Teams either skip this field entirely or pick a round number that sounds responsible. Set it where the cost of a wrong automated decision balances the cost of an unnecessary escalation, and write that reasoning into the document so the next person can move the line deliberately. Outputs. Every artifact the workflow produces, each with its destination: the decision, the record, the notification, the downstream call. The mistake is describing the output as the decision and leaving all the writes implied. Exception path. What happens to the cases the rules do not cover: who receives them, what context travels with them, and how fast. The mistake is writing route to a human and stopping, which produces an inbox rather than a path. Feedback loop. How the human decision on an exception gets back into the system so the confidence boundary moves over time. Without it, the system is frozen at the accuracy it launched with and degrades as the world drifts around it. Owner. One named person accountable for the rules, not a team and not a committee. Rules change, and change without an owner is how a working system quietly stops matching the business it was built for. Hand the document to a developer who has never attended a meeting about this workflow and ask whether they could build it. Not whether they could build something. Whether they could build this, with no follow-up conversation. If they would need to ask a question, the specification is not finished, and the question they would ask is exactly the ambiguity that surfaces later as a defect. The test converts an expensive problem into a cheap one, which is its whole value. The ambiguity costs a paragraph today. It costs a rebuild after launch, plus the credibility you spend explaining why the system does the wrong thing confidently. Many AI pilots never reach production, and the model is rarely what killed them. They die in the architecture layer nobody built: the pipelines, the confidence thresholds, the escalation logic, the feedback loops. The first missing piece of that layer is a specification, skipped in a week nobody scheduled, when somebody handed an engineer a sentence about a broken process and called it a brief. This is what forward deployment consists of most of the time. Not writing code. Sitting with the person who runs the process, pulling up the cases they actually handled, and refusing to leave until the judgment they have been carrying in their head is on paper in a form a system can execute.