# Building Workflows, Not Tool Stacks

This is an independently written lesson for the supplied topic. The Patch Desk workflow is an original example, not a reconstruction of Theo's paid lesson. We will connect the previous four lessons into one useful, reviewable process.

## Learning goals

- Define a workflow through its inputs, transitions, outputs, and acceptance conditions.
- Evaluate quality, user experience, security, and business value together.
- Add a tool only when it resolves a demonstrated gap in the workflow.

Theo's context-file discussion emphasizes feedback from checks and improving the codebase where agents repeatedly struggle. We use that public point to motivate an original end-to-end workflow. [Automatic captions, around 17:30–19:30](https://www.youtube.com/watch?v=GcNu6wrLTJc&t=1050).

## Begin with a completed job

Patch Desk's job is to turn a reported documentation mismatch into a verified correction that a maintainer can publish. Its job is not to use a particular number of agents or integrations. Start by describing the beginning and end: someone reports a problem; a reviewer receives a focused change with evidence. Everything between those points must serve that outcome.

Write down the minimum states: reported, investigated, edited, checked, reviewed, published, or blocked. Each transition needs evidence. A report becomes investigated when the mismatch has been compared with an authoritative source. Edited becomes checked when the acceptance command has actually run. Reviewed becomes published when the destination confirms that the intended version is live.

Anthropic distinguishes predefined workflows from systems where models choose their own actions in [Building effective agents](https://www.anthropic.com/engineering/building-effective-agents). It also discusses adding complexity only where needed. Use that distinction to make a design choice, not to rank architectures by sophistication. A predictable validation step can stay ordinary code while an agent investigates an ambiguous report.

## Quality is a chain of different checks

For our example, correctness means the command matches the project configuration. Scope means the change does not alter unrelated behavior. Readability means a contributor can understand when to use it. Reproducibility means another maintainer can repeat the check. Delivery means the reviewed version reaches the intended site. A single green indicator cannot establish all of these facts unless you know exactly what it measures.

Separate proposal quality from acceptance quality. An agent can suggest a useful edit that fails validation for an unrelated pre-existing issue. Conversely, the checker can pass an irrelevant edit. The maintainer needs both the artifact and a reason it addresses the request. Build the review around that relationship.

Also inspect the failure path. If a check times out, can the task resume without repeating publication? If the reviewer rejects the change, does the next attempt use that feedback? If the authoritative source is unavailable, does the workflow stop with a precise question instead of inventing a command? Reliability includes those branches, not only the successful demo.

## User experience is evidence made understandable

The user interface should reveal the state that matters to a person. A maintainer needs to know what changed, why it changed, how it was checked, and what decision remains. The agent may have inspected many files, but a wall of activity is not a substitute for a clear review packet.

For the fictional product, display “Correction ready for review” with the diff and check evidence. Do not say “Done” while the live guide still serves the old version. If publication fails, retain the reviewed correction and show the failed delivery step. Starting the entire investigation again would waste the user's time and might produce a different patch without a reason.

When the workflow includes forms, make errors actionable. W3C's [form-validation guidance](https://www.w3.org/WAI/tutorials/forms/validation/) covers identifying errors and helping users correct them. Applied here, “Report could not be submitted” is less useful than identifying the missing repository path and keeping the user's entered description intact. The principle is recovery, not merely adding a red error style.

## Security belongs in each transition

The investigation step reads untrusted reports and repository text. The publication step changes a public artifact. Those operations have different trust requirements. A report containing shell commands should not itself grant authority to execute them. A cited webpage should not be able to change who may publish.

The [OWASP prompt-injection guidance](https://cheatsheetseries.owasp.org/cheatsheets/LLM_Prompt_Injection_Prevention_Cheat_Sheet.html) discusses malicious instructions embedded in external content and the need for layered controls. For Patch Desk, the original design is to keep report text as data, restrict the working directory, separate read and write capabilities, and require the publication transition to use the approved artifact. No phrasing trick alone proves that hostile input is harmless.

Likewise, a tool's output should be useful evidence. The [MCP tool specification](https://modelcontextprotocol.io/specification/2026-07-28/server/tools) describes tool schemas and results. A protocol can standardize an interface, but the workflow still has to decide what a result means. “Upload request accepted” and “new page is live” remain different observations.

## Worked example: a small state machine

Here is original API-neutral pseudocode, not a runnable SDK sample:

```text
report = receive_report()
evidence = inspect_current_repository(report)
if evidence.is_insufficient:
    return blocked_with_missing_information()
patch = propose_focused_correction(evidence)
check = validate(patch)
if not check.passed:
    return review_packet(patch, check, publish_allowed=false)
approval = request_review(patch, evidence, check)
if approval.accepted:
    receipt = publish_exact_reviewed_artifact(patch)
    return verify_destination(receipt)
return preserve_feedback_for_revision(approval)
```

Walk one failure through it. The check passes, review accepts the correction, but the upload fails. The system should retain the exact reviewed artifact and failure receipt. A retry should publish that artifact, not generate an unreviewed replacement. If the artifact changes, review must apply to the new version. This is why identifiers such as a commit hash are useful in a delivery record.

Now connect the workflow to business value. Suppose the team spends substantial time explaining incorrect setup commands. A useful measurement is whether contributors can complete setup and whether support requests fall after the correction. Counting generated words or installed tools misses the outcome. Any numerical improvement would need actual observations; this fictional example claims none.

## Practice

Choose a recurring job and describe its states, transition evidence, owner, and failure recovery. Implement only the smallest useful path. One human review plus a local checker may be enough. Add an integration only after recording a specific gap, such as an inability to verify the published destination.

Acceptance criteria: the workflow produces an inspectable artifact; it names a real success check; it handles one failed check and one failed delivery without claiming success; and a person can identify the remaining decision. Your answer should explain why each tool is present and name at least one tempting tool you omitted because it did not solve a demonstrated problem.

## Check your understanding

1. Is a larger tool stack evidence of a better workflow? No. Judge completion, reviewability, and the actual user outcome.
2. Why retain artifact identity across review and publication? Approval of one version does not automatically approve another.
3. What should a failed delivery preserve? The reviewed artifact, its evidence, and the concrete failure needed for a safe retry.

## Sources

- [Anthropic: workflows and agents](https://www.anthropic.com/engineering/building-effective-agents).
- [W3C: accessible validation and error recovery](https://www.w3.org/WAI/tutorials/forms/validation/).
- [OWASP: prompt-injection controls](https://cheatsheetseries.owasp.org/cheatsheets/LLM_Prompt_Injection_Prevention_Cheat_Sheet.html).
- [MCP: tool interface specification](https://modelcontextprotocol.io/specification/2026-07-28/server/tools).