Patch-based AI edits for dashboard YAML¶

Problem¶

When AI refines an existing dashboard, it currently regenerates the entire YAML file. This has three problems:

Token waste: A 200-line dashboard YAML costs ~800 tokens to regenerate even if the edit is a single field change.
Error-prone: Full regeneration risks unintended changes — the LLM might silently drop a query, rename a variable, or reorder charts.
Merge conflicts: In multi-agent or collaborative workflows, full-file rewrites create unnecessary merge conflicts. A surgical patch to one chart wouldn't conflict with a patch to another.

json-render (Vercel Labs, 12k+ stars) solved this with three edit modes for multi-turn spec refinement: RFC 6902 JSON Patch, RFC 7396 JSON Merge Patch, and unified diff. Their system auto-selects the mode based on edit complexity. See ai_notes/research/json-render-deep-dive.md.

Context¶

Research origin: ai_notes/research/json-render-deep-dive.md — Priority 2 section. Inspired by Vercel's json-render edit modes (RFC 6902/7396/unified diff).
Current AI integration: dataface/ai/ — MCP server, prompts, tools
YAML compilation: dataface/core/compile/ — normalizer is source of truth
Cloud editor: apps/cloud/ — live YAML editing with htmx
YAML is nested (rows > charts > encodings), unlike json-render's flat element trees — this affects which patch strategies work well
Related task: streaming-yaml-generation-with-early-query-execution.md — streaming generation would pair naturally with patch-based edits

Possible Solutions¶

A. YAML-native merge patches (deep dict merge)¶

Define a simple merge-patch format in YAML itself:

# Merge patch: add color encoding to revenue chart
charts:
  revenue:
    color: region

Apply via deep merge (RFC 7396 semantics: null deletes, objects recurse, scalars replace). The AI outputs only the diff fragment, not the full file.

Pros: Simple, YAML-native, easy for LLMs to generate, human-readable. Cons: Can't express array insertions, reorderings, or deletions of non-null fields cleanly.

B. JSON Patch (RFC 6902) over compiled YAML¶

Use RFC 6902 patch operations targeting YAML paths:

[
  {"op": "add", "path": "/charts/revenue/color", "value": "region"},
  {"op": "remove", "path": "/queries/old_query"}
]

Pros: Full expressiveness (add, remove, replace, move, copy, test). Well-specified standard. Cons: JSON Patch paths don't map perfectly to YAML (arrays are index-based). More verbose for LLMs to generate. Less human-readable.

C. Unified diff on YAML text Recommended¶

AI generates a unified diff against the current YAML:

 charts:
   revenue:
     type: bar
     x: month
     y: revenue
+    color: region

Apply with standard diff/patch tooling or a simple Python patcher.

Pros: LLMs are very good at generating diffs. Human-readable. Handles any edit type. Familiar to developers. Works with existing diff/patch tooling. Cons: Fragile if the base YAML has been modified since the diff was generated (context mismatch). Requires line-level precision from the LLM.

D. Hybrid: merge for simple edits, diff for complex ones¶

Use merge patches (A) for single-field additions/changes. Fall back to unified diff (C) for structural changes (reordering rows, adding new sections). The AI prompt instructs the LLM which mode to use based on edit complexity.

Pros: Best of both worlds — simple edits stay simple, complex edits stay expressive. Cons: Two code paths to maintain. AI must choose correctly.

Plan¶

Implementation Progress¶

Review Feedback¶

Review cleared