Minimal Diff Formatter

Minimal Unified Diff Output Protocol (Delta-First Communication)

Overview

When presenting code modifications to a user or reviewer ("Here is the fix for the database connection leak"), default AI responses re-print the entire 300-line file inside a markdown code fence (```typescript ... ```).

Re-printing full files creates two severe problems:

1. Severe Token Waste: Emitting 300 lines of unchanged code burns 2,500+ expensive output tokens for a 3-line bug fix.
2. Poor Developer Experience: The human reviewer must scroll through hundreds of lines trying to spot what actually changed.

The Minimal Unified Diff Protocol formats all code modifications using standard Unified Diffs (```diff)** - displaying strictly the modified lines with **2 to 3 lines of surrounding context (- deletions, + additions).

Full-File Code Dump vs. Minimal Unified Diff

┌─────────────────────────────────────────────────────────────┐
│                 Output Presentation Impact                  │
│                                                             │
│  Full File Dump (300 Lines / 2,400 Tokens):                 │
│  ```typescript                                              │
│  import { Pool } from 'pg';                                 │
│  // 40 lines of setup...                                    │
│  export async function queryDb(sql) {                       │
│    const client = await pool.connect();                     │
│    try { return await client.query(sql); }                  │
│    finally { client.release(); } // <--- THE 1-LINE FIX!    │
│  }                                                          │
│  // 250 lines of other database handlers...                 │
│  ```                                                        │
│  ↳ 2,400 tokens billed, human must search for the change    │
│                                                             │
│  Minimal Unified Diff (10 Lines / 65 Tokens - 97.2% Cut):   │
│  ```diff                                                    │
│   export async function queryDb(sql) {                      │
│     const client = await pool.connect();                    │
│     try {                                                   │
│       return await client.query(sql);                       │
│  +  } finally {                                             │
│  +    client.release();                                     │
│     }                                                       │
│   }                                                         │
│  ```                                                        │
│  ↳ 65 tokens billed, change is instantly visible in 1 second│
└─────────────────────────────────────────────────────────────┘

The Unified Diff Syntax Standard

When emitting diffs in chat responses or walkthrough artifacts:

--- a/src/services/billing.ts
+++ b/src/services/billing.ts
@@ -52,7 +52,7 @@ export async function chargeCustomer(customerId: string, amount: number) {
   const customer = await getCustomer(customerId);
   if (!customer) throw new NotFoundError("Customer not found");

-  const result = await stripe.charges.create({ amount, customer: customer.stripeId });
+  const result = await stripe.paymentIntents.create({ amount, customer: customer.stripeId });
   return result;
 }

The 3 Rules of Unified Diff Formatting

1. Include 2-3 Lines of Anchor Context

Always provide 2 to 3 unchanged lines above and below the change (prefixed with a leading space) so the user and IDE can anchor the exact location.

2. Prefix Deletions with - and Additions with +

Never write comments like // changed this line. Use standard git-style + and - characters for native diff syntax highlighting in markdown renderers.

3. Omit Unchanged Functions

If a file contains 10 functions and you edited 1 function, output only the diff for that 1 function. Never include the 9 unchanged functions.

Production Python Unified Diff Generator

import difflib
from pathlib import Path

def generate_minimal_diff(
    original_code: str,
    modified_code: str,
    file_path: str = "file.ts",
    context_lines: int = 3
) -> str:
    """Generates a high-density unified diff between two code strings."""
    orig_lines = original_code.splitlines(keepends=True)
    mod_lines = modified_code.splitlines(keepends=True)
    
    diff = difflib.unified_diff(
        orig_lines,
        mod_lines,
        fromfile=f"a/{file_path}",
        tofile=f"b/{file_path}",
        n=context_lines
    )
    
    diff_text = "".join(diff)
    if not diff_text:
        return "[NO_CHANGES_DETECTED]"
        
    return f"```diff\n{diff_text}```"

Benchmark Comparison

Presenting 50 bug fixes to developer users:

Agent Operational Directive

MANDATORY: When displaying code modifications in chat or walkthrough artifacts, agents must output minimal unified diffs (```diff). Never re-print full source files when only a fraction of the lines were modified.