Your agent needs a diff

Do not index

While building the second workflow for Pailflow, I ran into a problem that had nothing to do with model quality.

This workflow takes a recorded client call and updates an existing scope document. There is already a base doc. After the call, that document needs to change.

The agent could generate updates just fine. The problem was reviewing them.

I was getting a new version of the document, but I could not easily tell what had changed relative to the original. For a scope that people build against, that is not acceptable.

Why full-document regeneration breaks review

When an agent regenerates a document, review becomes all-or-nothing.

You are forced to reread the entire file, even though most of it has not changed. The decision you are making is too large: is this whole thing correct?

That might be tolerable for drafts. It does not work for scopes, designs, or plans where small changes have real consequences.

The issue is not generation quality. It is that the interface hides the edit history.

Borrowing diffs from engineering

This problem already has a solution in software engineering.

Coding agents work inside repositories. Repositories have diffs. You never accept regenerated code. You review changes against the previous state.

That constraint is what makes coding agents usable. Review is focused on what changed, not on revalidating everything that stayed the same.

Knowledge work usually does not work this way. When humans edit docs, we rely on memory or coarse version history. You can revert, but you rarely see meaningful line-by-line differences.

That breaks as soon as an agent becomes the editor.

Implementing a diff viewer in the Pailflow workflow

For this workflow, the fix was straightforward.

Instead of producing a rewritten scope, the agent proposes edits against the existing document. Those changes are shown in a diff view alongside the original text.

Additions, removals, and modifications are explicit. I can approve changes, reject them, or leave notes inline.

This is still a v1 implementation, but the impact was immediate. Review time dropped. Cognitive load dropped. I stopped second-guessing whether something subtle had changed.

Most importantly, I could ship the updated scope with confidence.

Agents need reviewable changes, not rewritten documents

As agents take on more responsibility, interfaces need to make their actions legible.

The key question is not “what did the agent produce?”

It is “what did the agent change?”

Not a summary. Not a regenerated document. A real diff.

Without that, agents stay in demo territory. With it, they become tools you can actually use in production.

If you want, next step is tightening the language further or aligning this exactly with the YouTube video so the post reads like a written extension of the talk, not a duplicate.

Conclusion

If you want an agent you can ship, you need a diff.

That applies to scope docs, design files, project plans, and every other piece of knowledge work that agents will touch. The pattern is not new. Engineering proved it works. Now we need to apply it everywhere else.

If you want to follow along, I'm building PailFlow in the open and sharing how I'm using AI to scale a one-woman business.