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.

AspectFull regenerationJSON Patch
GranularityWhole documentField-level or array-level
Risk of driftHigh — content rewordedLow — untouched parts stay intact
Review effortRead entire new docReview small operation list
DeterminismPoor — non-deterministicGood — 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.
— Practical versioning principle

Concrete workflow for an agentic editor

  1. Parse the existing plain-text source into a structured tree (e.g., a JSON representation).
  2. Identify the intended change (e.g., replace finding #3, update the forecast table).
  3. Emit a JSON Patch with operations that touch only the affected parts.
  4. Apply the patch to the tree, then serialize back to plain text for human review.
  5. 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

unused
Diff size (regenerate)
missed
6%
Diff size (patch)
on track

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.