#+TITLE: Pattern catalog — two more worked examples from pearl prompts
#+DATE: [2026-05-28 Thu]
#+SOURCE: pearl session 2026-05-28, follow-up to earlier UI-patterns notes

* Two more pattern examples landed today

Both shipped in pearl as commit =505e707= on 2026-05-28. They sharpen earlier catalog candidates rather than introducing a new direction.

* Pattern 4: "The prompt label should match what the prompt does"

** Before

Pearl's filter-builder prompts and saved-query prompts both carried the same sentinel string at the top: =[ None. ]=. The label was uniform but the *behavior* was two different things:

- For filter dimensions (team, state, project, labels, assignee), picking the sentinel meant "no constraint on this dimension." Every value matches. That's *any*, not *none*.
- For the saved-query pick prompts (delete, run), picking the sentinel meant "don't act on anything." That's *cancel*, not *none* or *any*.

Craig caught this on 2026-05-28 during verify: "when does the choice presented in completing read say 'none' when the choice actually means 'any'? Find all these instances and a way to correct them."

** After

Two distinct sentinel constants with labels that match their behavior:

- =[ Any. ]= for filter dimensions
- =[ Cancel. ]= for pick-an-existing-thing prompts

A generic =pearl--with-sentinel SENTINEL CANDIDATES= helper lets each call site pick the label that fits. The predicate that recognizes opt-out (=pearl--filter-sentinel-value-p=) matches either sentinel or empty/nil so the downstream logic is uniform.

** Why for the catalog

This is the "no hidden affordances" pattern from the earlier note ([[file:2026-05-28-0003-from-pearl-rulesets-followup-no-empty-input.org]]) sharpened with a second rule: *if the affordance is visible, its label has to match what picking it does*. Visibility without accuracy is its own problem. A label that says "none" when the behavior is "any" is no better than an invisible empty-input idiom — both leave the user holding the wrong model.

Catalog shape suggestion: this is the same principle as Pattern 3, in a follow-up form. Either a single entry that captures both halves (visible + accurate) or two cross-linked entries.

* Pattern 5: "Default the most-common choice, not always 'yes'"

** Refinement of an earlier idea

In yesterday's discussion of yes/no prompts, the working principle was "default the choice to 'yes' so RET takes it." Craig pushed back today: "what I'm after is having the most common or preferred option be the one on top, not just 'yes' all the time."

** What that looks like in code

A new =pearl--read-yes-no PROMPT &optional DEFAULT= helper takes the default as an argument. The candidate list is ordered with the default first so the most-common choice is what the user sees at the top, the framework highlights it, and RET takes it without typing.

For pearl's three non-destructive yes/no prompts (open-issues-only, save-filter-locally, save-N-fields-across-M-issues), the default happens to be "yes" in each case because each is a do-the-thing-the-user-asked confirmation. But the helper signature makes the *next* prompt where "no" is more common a one-arg change, not a special case.

** Companion rule: friction proportional to consequence

The destructive yes/no prompts (delete issue, delete saved query, delete comment) deliberately stay as =yes-or-no-p=. Typing "yes" is a safety feature there, not friction to remove. The catalog entry should name this companion rule explicitly so the principle doesn't read as "always default-yes."

** Why for the catalog

This is a refinement of Pattern 3 ("no empty input as meaningful") rather than a new pattern. The cleaner phrasing is something like *the prompt's default is the choice the user most often wants, and the level of friction is proportional to the cost of the choice*. Two halves, one principle.

* Cumulative shape

After today's work, the catalog has five candidate patterns from pearl, all converging on the same underlying principle:

1. One-prompt picker with typed prefix (from 2026-05-27)
2. Transient state-buttons (from 2026-05-27, Craig's external reference)
3. No empty input as meaningful (from 2026-05-28, earlier today)
4. The prompt label matches what the prompt does (today's first refinement)
5. Default the most-common choice, with friction proportional to consequence (today's second refinement)

Patterns 1, 3, 4, 5 are arguably one principle in four shapes: *the choices the user has should all be on-screen, accurately labeled, ordered by what they'll most often want, with friction sized to the cost of being wrong*. Worth thinking about whether the catalog wants one entry that captures all four with worked examples, or four separate entries that cross-link. The single-principle-multiple-shapes form may scan more cleanly once five-plus patterns have accumulated.

* Standing by

Same as the earlier notes: spec-reviews welcome when the rulesets discussion produces a concrete shape.