A Case for Surgical Edits
The temptation of full regeneration
When you prompt an AI agent to "update the quarterly report," it’s tempting to have the model regenerate the whole document from scratch. The context is fresh, the wording can be improved, and you avoid brittle diffs. But this approach has a hidden cost.
Regeneration treats the existing document as a source of content rather than a source of truth. Every generated token is a chance for drift: numbers get subtly altered, phrasing changes against your will, structure breaks silent. The document isn’t being edited; it’s being replaced with a plausible confabulation.
JSON Patch: surgical, precise, reviewable
JSON Patch (RFC 6902) is a standard for expressing mutations to JSON documents as an array of operations — add, remove, replace, move, copy, test. When an AI agent edits a document, it can first load the current JSON, decide exactly what should change, and then emit a patch that embodies only those decisions.
Because the patch is data, not prose, it is automatically verifiable: you can apply it to the original document and check that the result satisfies all constraints. No hidden regenerations, no silent deletions.
| Aspect | Full regeneration | JSON Patch |
|---|---|---|
| Granularity | Whole document | Field-level or array-level |
| Risk of drift | High — content reworded | Low — untouched parts stay intact |
| Review effort | Read entire new doc | Review small operation list |
| Determinism | Poor — non-deterministic | Good — operations are explicit |
Why plain-text source unlocks the rest
A JSON document is a structured object, but humans write prose, markdown, or LaTeX. A plain-text source that follows a light markup (e.g., Markdown) can be parsed into a JSON-like tree — headings, paragraphs, lists, tables, code blocks. That tree is the natural target for JSON Patch.
Now it becomes easy: an agent edits a paragraph, moves a section, or corrects a number, and the patch records only that semantic change. Reviewing a patch feels like reviewing a redline, not diffing two entire documents.
The cost of an edit should be proportional to the size of the edit, not the size of the document.
Concrete workflow for an agentic editor
- Parse the existing plain-text source into a structured tree (e.g., a JSON representation).
- Identify the intended change (e.g., replace finding #3, update the forecast table).
- Emit a JSON Patch with operations that touch only the affected parts.
- Apply the patch to the tree, then serialize back to plain text for human review.
- Store the patch alongside the document, enabling rollback to any past state.
This turns an agent into a precision editor. It doesn’t need to rewrite what it doesn’t understand — it can leave the untouched parts exactly as they were.
Practical gains in one glance
94% smaller diffs
Measured impact of switching from regeneration to patch-based edits
Based on a 4-page quarterly report; the regenerated version touched every sentence.
In closing
If you want an agent to author whole essays, regeneration is fine. But if you want it to edit — to revise, to correct, to update — then a JSON Patch is the missing layer of precision.
The source isn’t merely a file; it’s a contract. A patch respects that contract by changing exactly what is agreed upon, nothing more. Pair that with plain-text source, and the full cycle becomes transparent, reviewable, and reversible.