1 files changed, 45 insertions, 0 deletions
diff --git a/patterns/one-prompt-picker-typed-prefix.org b/patterns/one-prompt-picker-typed-prefix.org
new file mode 100644
index 0000000..9de2060
--- /dev/null
+++ b/patterns/one-prompt-picker-typed-prefix.org
@@ -0,0 +1,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.