help: advanced-mode SQL forms collapse onto simple sibling (no distinct help content) #36

New Issue

2026-06-14T23:00:32+01:00

claude-clouddev1 commented

2026-06-14 23:00:32 +01:00

Summary

The in-app help command (H3) collapses the advanced-mode SQL command
forms onto their simple-mode siblings, so help <topic> does not show
distinct help for the SQL syntax — even though the simple-DSL and
advanced-SQL syntaxes are genuinely different.

Cause

The seven advanced-mode SQL command nodes — SELECT, WITH,
SQL_INSERT, SQL_UPDATE, SQL_DELETE, EXPLAIN_SQL (and any future
SQL form) — carry help_id: None in the grammar tree. Per the comment at
src/dsl/grammar/mod.rs:915-918, this is a deduplication mechanism for
the help command's list: they share an entry word with a simple
sibling, and note_help has no dedup, so giving them a help_id would
print the same command twice in the help list.

So the collapse was a deliberate list-formatting choice, not a
decision that advanced SQL forms need no distinct help content. As a side
effect, help <sql-form> (e.g. help select) has no help.<id> block to
resolve to.

Note: the parse-error / usage layer already distinguishes them —
ADR-0042 (H1a) §"the advanced usage block shows every form" renders each
form's usage on a parse error. So only the help command lags.

Why now

Surfaced while scoping H2 / hint (ADR-0053). H2 sidesteps this by
keying tier-3 hint content on a new dedicated hint_id (one per command
form, simple and advanced, each syntactically correct), rather than on
help_id. That fixes the hint surface but leaves the help surface
unchanged — hence this separate issue. help is shipped, ADR-backed
(ADR-0021/0023/0024) territory and deserves its own decision rather than a
silent rider on the hint ADR.

Scope to decide

Confirm current behaviour: what does help select / help (advanced
mode) actually produce for the SQL forms today?
Decide whether advanced-SQL forms should have distinct help
content, and if so how to key it without re-introducing duplicate
entries in the help list (e.g. dedup by entry word + mode, or a
distinct help key rendered only in advanced mode).
Keep consistent with the H2 hint_id approach (ADR-0053) so the two
contextual-help surfaces don't diverge.

Notes

Likely a small change once the keying decision is made.
Pedagogy-relevant: advanced mode is for students moving to raw SQL, so
accurate SQL-form help matters there specifically.

## Summary The in-app `help` command (H3) collapses the **advanced-mode SQL command forms** onto their simple-mode siblings, so `help <topic>` does not show distinct help for the SQL syntax — even though the simple-DSL and advanced-SQL syntaxes are genuinely different. ## Cause The seven advanced-mode SQL command nodes — `SELECT`, `WITH`, `SQL_INSERT`, `SQL_UPDATE`, `SQL_DELETE`, `EXPLAIN_SQL` (and any future SQL form) — carry `help_id: None` in the grammar tree. Per the comment at `src/dsl/grammar/mod.rs:915-918`, this is a **deduplication mechanism for the `help` command's list**: they share an entry word with a simple sibling, and `note_help` has no dedup, so giving them a `help_id` would print the same command twice in the `help` list. So the collapse was a deliberate *list-formatting* choice, **not** a decision that advanced SQL forms need no distinct help content. As a side effect, `help <sql-form>` (e.g. `help select`) has no `help.<id>` block to resolve to. Note: the **parse-error / usage layer already distinguishes them** — ADR-0042 (H1a) §"the advanced usage block shows every form" renders each form's usage on a parse error. So only the `help` command lags. ## Why now Surfaced while scoping **H2 / `hint`** (ADR-0053). H2 sidesteps this by keying tier-3 hint content on a new dedicated `hint_id` (one per command form, simple and advanced, each syntactically correct), rather than on `help_id`. That fixes the *hint* surface but leaves the *help* surface unchanged — hence this separate issue. `help` is shipped, ADR-backed (ADR-0021/0023/0024) territory and deserves its own decision rather than a silent rider on the hint ADR. ## Scope to decide - [ ] Confirm current behaviour: what does `help select` / `help` (advanced mode) actually produce for the SQL forms today? - [ ] Decide whether advanced-SQL forms should have distinct `help` content, and if so how to key it without re-introducing duplicate entries in the `help` list (e.g. dedup by entry word + mode, or a distinct help key rendered only in advanced mode). - [ ] Keep consistent with the H2 `hint_id` approach (ADR-0053) so the two contextual-help surfaces don't diverge. ## Notes - Likely a small change once the keying decision is made. - Pedagogy-relevant: advanced mode is for students moving to raw SQL, so accurate SQL-form help matters there specifically.

claude-clouddev1 added the enhancement label 2026-06-14 23:00:32 +01:00

oli referenced this issue from a commit

2026-06-15 17:02:09 +01:00

docs(adr): ADR-0053 — contextual `hint` command + F1 keybinding (H2)

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: oli/rdbms-playground#36