hint: pre-submit-diagnostic route + diagnostic.* tier-3 blocks (deferred from ADR-0053) #38

New Issue

2026-06-15T17:24:54+01:00

claude-clouddev1 commented

2026-06-15 17:24:54 +01:00

Summary

Deferred from H2 / ADR-0053 (Phase C): the pre-submit-diagnostic
route for the contextual hint — F1 on live input, when the cursor
sits on a typing-time diagnostic, rendering that diagnostic's tier-3
hint.err.<class> block — plus the ~33 diagnostic.* tier-3 blocks
themselves.

Why deferred

ADR-0053 D2 specified that the F1 live-input path reads the current
under-cursor diagnostic and renders its hint.err.<class> block. During
Phase C we found Diagnostic (src/dsl/walker/outcome.rs:194) carries
only severity / span / message (the already-rendered text) — not
its class key. So a live diagnostic can't be mapped to its
hint.err.<class> stem.

Wiring the route needs a class (or message_key) field added to
Diagnostic, threaded through every diagnostic-creation site across
the walker and validators — a broad mechanism change, plausibly larger
than the rest of Phase C, for the most marginal teaching value:

Pre-submit diagnostics are already surfaced by tier-2 — the ambient
panel shows the diagnostic message and the validity indicator
(ADR-0027) flags it while you type.
F1 already does something useful there today: with a diagnostic
present it shows the command block (e.g. insert's what/example/
concept), and tier-2 shows the diagnostic. No hole.
Many diagnostic.* classes overlap runtime error classes already
covered (type_mismatch, unknown_table ↔ not_found, arity ↔
invalid_value), so distinct content would largely duplicate them.

So v1 ships command-form hints + the 9 runtime error-class hints
(comprehensive for those); diagnostics are deferred here.

Scope to decide (when picked up)

Add class: Option<&'static str> (or message_key) to
Diagnostic; populate it at every creation site.
Wire the F1 live-input path: when an under-cursor diagnostic
exists, render hint.err.<class> for it (priority vs the command
block — likely diagnostic wins when present).
Decide content: author distinct hint.err.<diagnostic_class>
blocks, or reuse the runtime error-class blocks where a class has a
twin (type_mismatch, not_found, invalid_value, …) and only author
the genuinely-new ones (arity variants, ambiguous_column,
duplicate_cte, alias/projection issues, …).
Extend the H2 comprehensiveness coverage test to assert every
diagnostic class resolves to a hint block.

Notes

Additive to ADR-0053; the per-form/error keying already in place
doesn't lock it out. Likely its own small ADR amendment.
Pedagogy-led, not metrics-led (cf. issue #37).

## Summary Deferred from H2 / ADR-0053 (Phase C): the **pre-submit-diagnostic route** for the contextual `hint` — F1 on live input, when the cursor sits on a typing-time diagnostic, rendering that diagnostic's tier-3 `hint.err.<class>` block — plus the ~33 `diagnostic.*` tier-3 blocks themselves. ## Why deferred ADR-0053 D2 specified that the F1 live-input path reads the current under-cursor diagnostic and renders its `hint.err.<class>` block. During Phase C we found `Diagnostic` (`src/dsl/walker/outcome.rs:194`) carries only `severity` / `span` / `message` (the already-rendered text) — **not its class key**. So a live diagnostic can't be mapped to its `hint.err.<class>` stem. Wiring the route needs a `class` (or `message_key`) field added to `Diagnostic`, threaded through **every** diagnostic-creation site across the walker and validators — a broad mechanism change, plausibly larger than the rest of Phase C, for the **most marginal** teaching value: - Pre-submit diagnostics are already surfaced by **tier-2** — the ambient panel shows the diagnostic message and the validity indicator (ADR-0027) flags it while you type. - F1 already does something useful there today: with a diagnostic present it shows the **command** block (e.g. insert's what/example/ concept), and tier-2 shows the diagnostic. No hole. - Many `diagnostic.*` classes overlap runtime error classes already covered (`type_mismatch`, `unknown_table` ↔ `not_found`, arity ↔ `invalid_value`), so distinct content would largely duplicate them. So v1 ships command-form hints + the 9 runtime error-class hints (comprehensive for those); diagnostics are deferred here. ## Scope to decide (when picked up) - [ ] Add `class: Option<&'static str>` (or `message_key`) to `Diagnostic`; populate it at every creation site. - [ ] Wire the F1 live-input path: when an under-cursor diagnostic exists, render `hint.err.<class>` for it (priority vs the command block — likely diagnostic wins when present). - [ ] Decide content: author distinct `hint.err.<diagnostic_class>` blocks, or reuse the runtime error-class blocks where a class has a twin (type_mismatch, not_found, invalid_value, …) and only author the genuinely-new ones (arity variants, ambiguous_column, duplicate_cte, alias/projection issues, …). - [ ] Extend the H2 comprehensiveness coverage test to assert every diagnostic class resolves to a hint block. ## Notes - Additive to ADR-0053; the per-form/error keying already in place doesn't lock it out. Likely its own small ADR amendment. - Pedagogy-led, not metrics-led (cf. issue #37).

claude-clouddev1 added the enhancement label 2026-06-15 17:24:54 +01:00

oli referenced this issue from a commit

2026-06-15 17:56:51 +01:00

docs(hint): defer pre-submit-diagnostic route + diagnostic.* blocks (ADR-0053)

oli referenced this issue from a commit

2026-06-22 20:54:17 +01:00

docs(handoff-76): tee up the open issues as the next session's focus

claude-clouddev1 commented

2026-06-24 10:43:46 +01:00

Closing — decided not to build the pre-submit-diagnostic tier-3 route (do/defer/close call, 2026-06-24).

The deferral reasons recorded in ADR-0053 (D6) still hold and outweigh the value:

Broad change, structural. Diagnostic (walker/outcome.rs) carries only its rendered message, not a class key — so mapping a live pre-submit diagnostic to a diagnostic.* tier-3 block needs a class field threaded through every diagnostic-creation site.
Marginal value. Tier-2 already surfaces pre-submit diagnostics live (ambient message + the ADR-0027 validity indicator); F1 already shows the useful per-form command block when a diagnostic is present; and several diagnostic classes duplicate runtime error classes already covered by ADR-0053's hint.err.* and ADR-0058's clause-concept layer.

The higher-value sibling extension — clause-concept hints (#37) — is done (ADR-0058). The keying doesn't lock this out: a diagnostic.* layer can be added additively later.

Reconsider if a concrete need emerges — e.g. a diagnostic class with genuinely unique teaching value not already served by the command / error / clause-concept tiers.

Closing — **decided not to build** the pre-submit-diagnostic tier-3 route (do/defer/close call, 2026-06-24). The deferral reasons recorded in ADR-0053 (D6) still hold and outweigh the value: - **Broad change, structural.** `Diagnostic` (`walker/outcome.rs`) carries only its rendered `message`, not a class key — so mapping a live pre-submit diagnostic to a `diagnostic.*` tier-3 block needs a `class` field threaded through *every* diagnostic-creation site. - **Marginal value.** Tier-2 already surfaces pre-submit diagnostics live (ambient message + the ADR-0027 validity indicator); F1 already shows the useful per-form command block when a diagnostic is present; and several diagnostic classes duplicate runtime error classes already covered by ADR-0053's `hint.err.*` and ADR-0058's clause-concept layer. The higher-value sibling extension — clause-concept hints (#37) — is done (ADR-0058). The keying doesn't lock this out: a `diagnostic.*` layer can be added additively later. **Reconsider if** a concrete need emerges — e.g. a diagnostic class with genuinely unique teaching value not already served by the command / error / clause-concept tiers.

claude-clouddev1 closed this issue

2026-06-24 10:43:46 +01:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: oli/rdbms-playground#38