Anatomy of a workflow automation spec (the document that keeps AI projects honest)

Every automation post-mortem I’ve been part of starts the same way: the demo was great. The room watched a document get classified, a reminder go out, a status flip to done, and everyone agreed the thing worked. What died between the demo and production was never the model. It was everything the demo skipped — the weird cases, the permissions, the definition of finished — and there is exactly one artifact that forces all of it into the open before money is spent: the spec.

Gartner predicted that at least 30% of generative AI projects would be abandoned after proof of concept, citing poor data quality, inadequate risk controls, and unclear business value. Read that list again. Not one item on it is about model capability. All of them are things a spec settles before the build starts, which is why I’ve come to believe the spec is the highest-leverage document in an AI project, and also why nobody wants to write it. It’s boring. That’s the job.

I’ll walk through the anatomy using a real example: the intake-automation spec I wrote for a composite client, an accounting firm assembled from patterns across real engagements rather than a disguised real firm. The workflow is client document intake during tax season — “the doc chase” — which was consuming about 2,100 admin hours a year. The build was a $52K statement of work. The spec runs seven pages, and every section below is one of the reasons it ships instead of dying.

The current-state swimlane nobody flatters

The first section documents how the work happens today, and the entire discipline is refusing to clean it up. The composite spec’s current-state diagram contains the line “admin chases by memory,” because that was the process. Which clients still owed documents lived in the heads of three admins and whatever personal reminders they had set for themselves. When one of them was out sick, chasing stopped for her client list.

If your current-state diagram looks orderly, it has been flattered, and you are about to build an automation for a process that doesn’t exist. The unflattered version also protects the ROI math: 2,100 hours is only a defensible number because the spec documents where those hours actually go, which means the after-number will be measured against something real instead of against a diagram someone drew to look competent.

A document request is in exactly one of eight states

The heart of the spec is a state machine. In the composite version, every document request is in exactly one of eight states: requested, reminded, received, classified, filed, verified, complete, or exception. Every transition has a trigger and an owner. The chasing cadence stops being tribal knowledge and becomes rules a system can execute: day 3, reminder email; day 7, second email plus a task in the practice-management system; day 12, a task for an admin to call.

If you can’t draw the states, you’re automating a vibe. I mean that literally. “Automate the doc chase” is a vibe. “Move requests from reminded to received and route everything weird to a human” is a system.

Two of the states deserve special attention. Classified is where the LLM lives: incoming documents get labeled W-2, 1099, K-1, prior-year return, and so on. The spec requires a confidence threshold — above it, the document is auto-filed; below it, the document goes to a human queue. This is not hedging, it’s arithmetic. A classifier that is right 94% of the time and never says “not sure” is worse than one that is right 90% of the time and flags its doubts, because the first one sends every error silently downstream into a client’s tax return, and the second one sends its errors to a person.

Filed is where data readiness bites. The spec defines the naming convention and the destination structure for every document, because an intake automation is only as good as where the documents land. Gartner found that 63% of organizations either lack AI-ready data practices or aren’t sure they have them, and expects 60% of AI projects without AI-ready data to be abandoned through 2026. If “filed” means “somewhere on the shared drive,” you have automated the manufacture of the mess your next AI project will choke on.

The exception queue is where trust is won

The composite spec names four exception triggers: a wrong document, an illegible scan, a consent flag under §7216 — the rule governing disclosure of tax-return information — and classifier confidence below the 0.85 threshold. All four route to a named human queue. None of them is ever auto-resolved.

“Never auto-resolved” is the load-bearing phrase in the entire document. In the first month of any automation, staff are not watching the happy path; they’re watching what the system does with the weird cases, because the weird cases are where their professional judgment lives. Route those to a human, visibly, and staff conclude the system knows its limits. Let the system guess on a consent flag even once, and you haven’t lost a document, you’ve lost the automation — because from that day forward staff re-check everything it touches, and an automation everyone re-checks saves nothing.

The automation reads only what the requesting human could read

One sentence in the spec does more security work than everything else combined: the automation operates with the permissions of the human whose request triggered it, never more. No service account with standing access to the whole document store. If the admin running the chase couldn’t open a folder, neither can the workflow acting on her behalf.

This rule costs real engineering time, and the spec should show that cost honestly. On the composite build, the engineering team proposed a service-account shortcut; rejecting it added four days to the schedule. Cheap, against the alternative. IBM’s 2025 Cost of a Data Breach report found that 13% of organizations had already reported breaches of AI models or applications, and 97% of the breached organizations lacked proper AI access controls. Ninety-seven percent is not a subtle signal about which corner gets cut. The spec is where you make cutting it impossible, because the rule is written down before anyone is behind schedule.

Acceptance criteria a managing partner can verify

The spec commits, in numbers, to what “working” means: recover at least 60% of the 2,100 documented admin hours, measured against the time study in the current-state section, with a user-acceptance week and a scheduled go/no-go gate review before full rollout. The test of an acceptance criterion is whether a managing partner — someone who will never read a line of code — can personally check it. “The system works well” fails that test. “Requests reach received without human touches at least 60% of the time, and here’s the report” passes it.

Vague acceptance criteria are how demos sneak into production. If nobody wrote down what done means, the vendor’s definition wins, and the vendor’s definition is the demo.

Change control: scope creep gets priced, in writing

Midway through the composite build, someone asked a perfectly reasonable question: shouldn’t the system chase e-signatures too? The spec’s change-control section converted that from hallway pressure into a decision with a price tag: plus $9K and three more weeks. Priced that way, the answer was easy — deferred to v1.1, in writing. Without a change-control section, that same request becomes an argument, and unpriced reasonable requests are how a $52K build becomes an $80K disappointment that ships late and validates every skeptic in the building.

The mechanism protects both directions, which is what makes it fair. When a stakeholder later asked whether syncing amended organizers would cost extra, the spec answered the question: it was already in scope. Change order, $0. The same page that shields the budget from creep shields the client from being re-billed for what they already bought.

None of this is exciting to write, and that’s the point. The spec is where excitement goes to get priced. The composite version is published in full: the sample Workflow Automation Spec — all seven pages, for a composite client — plus the sample deliverables library. Steal the section headings. The document that keeps an AI project honest is boring, and it is supposed to be.