1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
|
#+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.
|
