Skip to content

Interpretation Walkthrough

An explanatory review — instantiates Grammar-Guided Structure Recovery

A human-readable, step-by-step account of why the parser recovered this structure — each node traced back to the rule that licensed it and the input span it covers.

The Interpretation Walkthrough makes a recovered structure inspectable. Given a parse, it renders the derivation as a narrated account a person can follow: for each node, which grammar rule licensed it and which span of the input it grounds in, in an order a human can read. It neither produces the structure (the parser did that) nor checks whether the structure is legal (validation does that); its single job is to convert an opaque internal derivation into a provenance-linked story that a non-implementer can audit and challenge. Its defining move is that every claim it makes is a real link — this node exists because of that rule over those characters — so the parse stops being a verdict to accept on faith and becomes an argument that can be checked.

Example

A spreadsheet user sets A1 = 2, A2 = 3, and writes =A1 + A2 * 3, expecting 15. The cell shows 11, and the user is convinced the tool is broken. The Interpretation Walkthrough answers, in the user's terms: "* binds tighter than +, so A2 * 3 is formed first — that's the 9 — grounded in characters 6–11. Then A1 + (that) gives 2 + 9 = 11, grounded in the whole formula." Each step names the rule that fired and the exact span it covers.

The user did not need the parse tree, the grammar, or the source code — they needed the why, laid out step by step against their own input. Seeing it, they add parentheses and move on. The same walkthrough, rendered for an implementer instead, would name the productions and offsets outright; the derivation underneath is identical, only the register changes.

How it works

The walkthrough traverses the recovered parse and, for each node, emits a triple: the rule applied, the input span covered, and the constituent produced — sequenced in an order the reader can follow (usually the order of composition). Every statement is anchored to a specific input position and a specific rule, so the account is a rendering of the actual derivation rather than a plausible retelling of it. What distinguishes it from a raw tree dump is selection and phrasing: it is authored for comprehension, surfacing the steps that matter to its intended reader and suppressing the mechanical noise that doesn't.

Tuning parameters

  • Granularity — narrate every reduction, or only the decision points a human cares about. Finer is complete but noisier.
  • Audience register — implementer-facing (rule names, byte offsets) vs. end-user-facing (plain-language why). Pick the reader before the phrasing.
  • Provenance depth — link back to raw offsets, to tokens, or to source lines. Deeper is more precise and more verbose.
  • Focus — walk the whole derivation, or highlight only the contested and ambiguous nodes where the reader's disagreement is likely to land.
  • Ordering — by composition order, by input order, or by importance.

When it helps, and when it misleads

Its strength is trust: it turns an opaque parse into something a human can verify or contest, which is indispensable for debugging, user support, and any setting where a machine's structural decision must be defensible to someone who didn't build it. Its danger is that a walkthrough is a rendering, and a rendering can drift from what actually happened. If the account paraphrases the derivation instead of tracing it, it can present a tidy, convincing story that is not what the parser did — and a wrong explanation is worse than none, because it is believed. The classic misuse is exactly this run-backwards failure: generating a plausible-sounding walkthrough after the fact that rationalizes the output rather than reproducing the derivation. The discipline that guards against it is to generate the walkthrough mechanically from the real parse, with provenance that is genuine links rather than reconstructed prose, so it cannot say anything the derivation didn't do.[1]

How it implements the components

The Interpretation Walkthrough realizes the provenance component — and only it — turning the recovery's internal record into something legible:

  • provenance_record — each step links a recovered node to the exact input span and grammar rule that produced it; the walkthrough is that provenance made human-readable and navigable.

It does not check whether the structure is valid (that is Linting or Validation Rule and Semantic Schema Validation), does not record the ambiguities recovery left unresolved (that is the Ambiguity Register), and does not keep the machine-checkable conformance audit (that lives with Semantic Schema Validation); it renders an already-recovered structure for a human.

Notes

The load-bearing constraint is that the walkthrough must be derived from the real parse, not reconstructed after it. The moment it is generated from the output rather than the derivation, its provenance links become decoration and it stops being an audit — it becomes storytelling that happens to agree with the answer, which is precisely the failure it exists to prevent.

References

[1] A parse tree (or derivation) is the record of exactly which grammar rules were applied, in what order, over which spans, to recover a structure. Because the walkthrough is a reading of that derivation rather than a summary of the output, it can be checked step by step against the input — which is what a genuine provenance record buys over a plausible narrative. ↩