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
46
47
48
49
50
|
#+TITLE: UI pattern standardization across projects
#+DATE: [2026-05-27 Wed]
#+SOURCE: pearl issue-sources Phase-5 verify walk-through
* Context
Surfaced during pearl issue-sources verify on 2026-05-27. A pattern landed in pearl that Craig liked and asked how to standardize across projects so the next project benefits. This is the cross-project meta-question he wanted filed somewhere his agenda would catch it.
* Two patterns worth naming
** "All info you need, in one completing-read"
What pearl's =pearl-pick-source= does: every fetch source (Linear favorites + saved queries) goes into one =completing-read= with a typed prefix and the name. The candidate string reads as =[view] Active bugs= / =[project] Platform= / =[saved] My open=, sorted by Linear's =sortOrder= then alphabetically. The user sees kind, identity, and natural rank in one scan, picks once, and is done. No second prompt to disambiguate, no mode switch, no menu chain.
Cost was a small helper that maps source-plist to display string. The win was the picker collapsing to one decision rather than three.
The pattern generalizes anywhere a project has N candidates and the *kind* of candidate matters as much as the name. Pearl reaches for it again in the planned ad-hoc builder rewrite and in =pearl-refine-current-source=.
** The "magit transient" pattern (Craig's specific reference)
A bottom-popup screen with toggleable button rows showing current state, with key bindings printed inline, and a single keybinding to summon it. The reference is magit's =transient.el= library, which is actual library code rather than just a UI convention. Craig described the music-player UX equivalent. The win is "all the levers in one place, with affordances visible, and one chord to get there from anywhere."
Pearl uses transient lightly today (=pearl-menu= behind =C-; L m=) but doesn't yet exploit toggleable state-indicator buttons. The ad-hoc builder rewrite would be a natural place.
* The meta-question
Craig's actual question isn't about either pattern. It's: *how do good patterns travel from project A to project B?*
Three angles worth thinking through:
1. *A pattern catalog.* A written record of patterns that worked, with the context that made each one work. Lives somewhere durable. Without it, every project re-derives the same patterns from scratch and the discoveries don't compound.
2. *A surfacing mechanism.* Even with a catalog, how does the right pattern show up at the right moment? "You're about to write a multi-prompt completing-read chain. Consider the one-prompt + typed-prefix shape instead." A passive catalog only helps if Craig or the agent thinks to consult it. Active surfacing is the harder problem.
3. *Where patterns live.* Three plausible homes: this rulesets repo (next to existing rules + skills), a Linear-style document workspace, or per-project notes that cross-link. Each shapes who reads them and when. Rulesets has the agent-visibility advantage. Every session loads it.
* My read on spec scope
Brainstorm-level, not implementation-ready. The questions above aren't one-line decisions:
- Does the catalog get a structured format (one pattern per file, frontmatter, slug) or a free-form doc?
- Is the surfacing mechanism agent-driven (the model spots the pattern opportunity) or human-driven (Craig grep-searches when he feels stuck)?
- Does the catalog include anti-patterns (things that didn't work, with the reason) or only what worked?
- How do patterns get into the catalog? Every time one lands, or batch reviews on cadence?
A one-page spec along the lines of pearl's =docs/issue-sources-spec.org= (problem + design + open questions + acceptance) would land the shape before any implementation. Recommend doing that before writing any catalog file or any agent prompt change.
* What I might be pulled in for
Craig flagged he'd work on this with the rulesets project and that spec-reviews might come back this way. Standing by for those.
|
