Wishlist: structured explanations with assembly line anchors (explanation-to-assembly linking)

[mattgodbolt-molty]

Wishlist item preserving the idea from #14, which was closed unbuilt-upon (no frontend consumer was planned) after going stale against a heavily-evolved codebase. That PR remains a useful API-side sketch if this is ever picked up. Written up by Molty on Matt's behalf.

The idea

An opt-in format: "structured" on the explain request returns the explanation as machine-readable JSON instead of a markdown blob:

• summary: one-sentence overview
• sections[]: each with title, markdown content, and asmStartLine/asmEndLine anchoring the section to the assembly lines it describes
• keyInsight: the single most important takeaway

The line anchors are the point: every paragraph knows which instructions it is about.

What it would enable in the CE frontend

CE already does hover-linking between the source and assembly panes (coloured spans driven by source mappings). Structured explanations let the explain pane join as a third participant:

1. Hover an explanation section, and its assembly lines highlight (Monaco decorations, same UX grammar as source-to-asm linking).
2. Click an assembly line, and the explain pane scrolls to the section covering it (reverse index over the ranges).
3. Progressive disclosure: show summary + keyInsight by default (a two-line answer instead of a wall of text), expand sections on demand. Much friendlier in small panes.
4. Further out: gutter markers or hover tooltips on the assembly itself, or an "explain this selection" flow surfacing only the overlapping sections.

The frontend half is the larger piece of work and was never started; that, plus no plans to consume the output, is why #14 was closed.

Implementation caveats (learned from the #14 sketch and since)

• Line-index drift is the sharp edge. The anchors refer to the filtered assembly the service sends Claude: after the 300-line smart selection, omission markers, and the character caps added in Enforce hard character caps on source and assembly inputs #20. The frontend needs the same index mapping the service applied, or anchors point at the wrong pane lines. Consider having the service return the mapping (or anchor to the original pane indices server-side) rather than making the client reconstruct it.
• A fresh implementation should use client.messages.parse() with a Pydantic model rather than hand-rolled output_config + model_validate_json as in Add structured output format with assembly line mappings #14; structured outputs are GA and the SDK does schema-validation and retries now.
• Structured mode forks the cache key (markdown and structured responses cache independently).
• Structured outputs are incompatible with citations, and whole-response JSON precludes progressive rendering of the markdown content.
• The Add structured output format with assembly line mappings #14-era prefill incompatibility is moot (assistant prefill no longer exists in the codebase).
• Re-run the prompt-test eval for the structured path before shipping: forcing a JSON schema changes how the model allocates attention, so accuracy on the 21-case suite needs re-checking against the markdown baseline (same word-budget guidance applies inside sections[].content).

🤖 Written by Molty (Claude) on behalf of @mattgodbolt