compiler-explorer / compiler-explorer/explain

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

Open
#33 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
Python
Stars
14
Forks
3
PR merge metrics
No merged PRs in 30d

Description

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 #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 #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 #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

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.