hint: clause-concept hints (deferred extension of ADR-0053) #37

New Issue

2026-06-15T11:46:55+01:00

claude-clouddev1 commented

2026-06-15 11:46:55 +01:00

Summary

A deferred extension of the contextual hint feature (H2 / ADR-0053):
clause-concept hints — deeper teaching surfaced when the cursor sits
in a recognized clause within a command, distinct from the per-form
tier-3 block.

Background

ADR-0053 delivers tier-3 hints at per-form granularity (one
what/example/concept block per command form, e.g.
hint.cmd.add_relationship), plus a live Next: line. Position-awareness
within a form is otherwise owned by tier-2 (the ambient candidate list /
slot prose).

During Phase B we identified a third "point" the per-form model doesn't
serve: concepts that live inside a clause, where a learner may want
teaching deeper than tier-2's candidate list but narrower than the whole
form. Examples:

… on delete ⟨cascade | set null | restrict⟩ — referential actions
create table … ( …, ⟨primary key | unique | check | foreign key⟩ … )
— the constraint slots
the with pk clause
1:n / m:n cardinality

Proposed direction (not yet designed)

A hint.concept.<topic> catalogue namespace, surfaced when the cursor
is detected to be in a recognized clause, layered on top of the
per-form block (does not replace it).
Cursor-context detection: identify the clause from the walker /
grammar position. This is the main new mechanism.
ADR-0053's per-form keying does not lock this out — it is an
additive layer.

Why deferred, not empirical

We do not expect to accumulate usage statistics that would tell us which
clauses learners pause at, so this won't be "data-driven later" — it is a
deliberate follow-up job to be designed and scoped on its own once the
per-form tier-3 layer (ADR-0053 Phases A–D) is in real use. Pedagogy-led,
not metrics-led.

Scope to decide (when picked up)

Which clauses get concept hints (start with referential actions +
constraint slots — the highest-value relational concepts).
Cursor-in-clause detection mechanism (walker position → clause id).
Catalogue structure (hint.concept.<topic> + the same
what/example/concept shape?) and keys.rs coverage.
How it composes with the per-form block in the rendered output.
Likely its own ADR (amends/extends ADR-0053 D3/D4).

## Summary A deferred extension of the contextual `hint` feature (H2 / ADR-0053): **clause-concept hints** — deeper teaching surfaced when the cursor sits in a recognized *clause within a command*, distinct from the per-form tier-3 block. ## Background ADR-0053 delivers tier-3 hints at **per-form** granularity (one `what`/`example`/`concept` block per command form, e.g. `hint.cmd.add_relationship`), plus a live `Next:` line. Position-awareness *within* a form is otherwise owned by tier-2 (the ambient candidate list / slot prose). During Phase B we identified a third "point" the per-form model doesn't serve: **concepts that live inside a clause**, where a learner may want teaching deeper than tier-2's candidate list but narrower than the whole form. Examples: - `… on delete ⟨cascade | set null | restrict⟩` — referential actions - `create table … ( …, ⟨primary key | unique | check | foreign key⟩ … )` — the constraint slots - the `with pk` clause - `1:n` / `m:n` cardinality ## Proposed direction (not yet designed) - A `hint.concept.<topic>` catalogue namespace, surfaced when the cursor is detected to be in a recognized clause, layered **on top of** the per-form block (does not replace it). - Cursor-context detection: identify the clause from the walker / grammar position. This is the main new mechanism. - ADR-0053's per-form keying does **not** lock this out — it is an additive layer. ## Why deferred, not empirical We do not expect to accumulate usage statistics that would tell us which clauses learners pause at, so this won't be "data-driven later" — it is a **deliberate follow-up job** to be designed and scoped on its own once the per-form tier-3 layer (ADR-0053 Phases A–D) is in real use. Pedagogy-led, not metrics-led. ## Scope to decide (when picked up) - [ ] Which clauses get concept hints (start with referential actions + constraint slots — the highest-value relational concepts). - [ ] Cursor-in-clause detection mechanism (walker position → clause id). - [ ] Catalogue structure (`hint.concept.<topic>` + the same `what`/`example`/`concept` shape?) and `keys.rs` coverage. - [ ] How it composes with the per-form block in the rendered output. - [ ] Likely its own ADR (amends/extends ADR-0053 D3/D4).

claude-clouddev1 added the enhancement label 2026-06-15 11:46:55 +01:00

oli referenced this issue from a commit

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

feat(hint): H2 Phase B — per-form keying + the three exemplars (ADR-0053)

claude-clouddev1 referenced this issue

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

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

Sign in to join this conversation.