#+TITLE: One-prompt picker with typed prefix
#+SLUG: one-prompt-picker-typed-prefix
#+PRINCIPLE: When the kind of candidate matters as much as its name, put kind and name in one picker with a typed prefix so the user picks once.
#+PROBLEM: A multi-prompt chain to first choose a kind, then an item within it, adds modal moments the user has to track.
#+TAGS: completing-read picker prompts disambiguation
#+SOURCE: pearl pearl-pick-source (issue-sources), handoff note 2026-05-27
#+EXAMPLES: pearl pearl-pick-source

* Problem

A project has N candidates of several kinds, and the kind matters as much as the name. The reflexive shape is a chain: first prompt for the kind (view? project? saved query?), then a second prompt for the item within that kind. Every extra prompt is a mode switch the user holds in their head, and the kind/name split is artificial. The user already knows the specific thing they want.

* Do

Put every candidate into one =completing-read=, each rendered as =[kind] name=, sorted by the kind's natural order then alphabetically. The user sees kind, identity, and rank in one scan, picks once, and is done.

Before, two prompts:

#+begin_example
Source kind: view / project / saved
(then) View: Active bugs / Recent / ...
#+end_example

After, one prompt:

#+begin_example
Source: [view] Active bugs
        [view] Recent
        [project] Platform
        [saved] My open
#+end_example

The only cost is a small helper that maps each candidate's metadata to its display string. The win is the picker collapsing three decisions to one.

* Anti-pattern

A prompt chain that disambiguates by kind first and item second, when the user already has a specific item in mind. The intermediate "which kind?" prompt is a decision the combined picker never makes the user state.

* Applicability

Reach for it anywhere N candidates span multiple kinds and the kind is worth showing. It stops being right when the candidate list is too large to scan in one pass (then a kind filter earns its prompt), or when picking the kind genuinely narrows an expensive downstream fetch.

* Related

A facet of the root principle (see [[file:README.org][README]]): all the choices on screen, ordered by what the user most often wants.