From db7f82711978da5e7f152297942854c7b753f480 Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Thu, 28 May 2026 08:18:10 -0500 Subject: chore(audit): task-audit pass + pearl intake from 2026-05-28 morning All 16 open tasks bucketed and updated. 14 received autonomous Phase C edits (13 type-tag additions per the new scheme plus #15's body refresh for the accumulating pearl signal). Phase D adjudicated two priority bumps and the morning's inbox spillover. Phase E stamped :LAST_AUDIT: in notes.org Workflow State. Autonomous Phase C: - Tagged tasks 1-11 and 13-14 with their type tag (:feature:, :chore:, :spec:), bumped LAST_REVIEWED to 2026-05-28. Tasks 12, 15, 16 already carried type tags. - Refreshed task #15 body to reference the four pearl pattern-catalog notes now in docs/design/ (six worked patterns total). Phase D adjudication: - #15 (cross-project pattern catalog) bumped [#C] to [#B]. Pearl shipped 6 worked examples plus a synthesizing principle and is asking for spec-review iterations. Design questions still open but evidence is past the tipping point. - Filed new [#B] :feature: TODO for the codex Phase 1 race-fix (AI_AGENT_ID + session-context.d/.org), lifted from the broader runtime spec (#16). Phase 1 alone is low-risk and fixes a real correctness issue under simultaneous agents. Pearl intake (4 inbox files from this morning): - Moved 0155 (patterns 4-5) and 0303 (pattern 6) into docs/design/ alongside the prior two pattern-catalog notes. Referenced from #15. - Filed new [#C] :chore:quick:solo: TODO for pearl 0138's --archive-done sweep at the start of open-tasks.org Phase A. - Filed new [#C] :feature:solo: TODO for pearl 0226's spec-review.org Phase 6 implementation-task enumeration. - Deleted 0124. Already implemented this session as the audit-warranted pre-step plus the LAST_AUDIT stamp now live in the workflow files. --- .../2026-05-28-pattern-catalog-prompt-collapse.org | 88 ++++++++++++++++++++++ ...-pattern-catalog-prompt-labels-and-defaults.org | 69 +++++++++++++++++ 2 files changed, 157 insertions(+) create mode 100644 docs/design/2026-05-28-pattern-catalog-prompt-collapse.org create mode 100644 docs/design/2026-05-28-pattern-catalog-prompt-labels-and-defaults.org (limited to 'docs') diff --git a/docs/design/2026-05-28-pattern-catalog-prompt-collapse.org b/docs/design/2026-05-28-pattern-catalog-prompt-collapse.org new file mode 100644 index 0000000..bef4516 --- /dev/null +++ b/docs/design/2026-05-28-pattern-catalog-prompt-collapse.org @@ -0,0 +1,88 @@ +#+TITLE: Pattern catalog — collapse N orthogonal prompts into one enriched prompt +#+DATE: [2026-05-28 Thu] +#+SOURCE: pearl session 2026-05-28, third follow-up to UI-patterns thread + +* Pattern 6 (or refinement of 4): "Collapse N orthogonal prompts into one enriched prompt where each candidate is a complete end-state" + +Shipped as a design decision in =docs/saved-query-sync-spec.org= on 2026-05-28 during sprint review. Sharpens earlier catalog candidates rather than introducing a new direction. + +** The trigger + +Craig, while reviewing the spec's sync-saved-query-to-linear command: "have we informed the user if this choice is consequential in any way? this almost feels as if we can collapse two levels together by adding more information to each individual choice." + +The spec originally proposed two sequential prompts: +1. Team scope: =[ Personal. ]= / Engineering / Marketing / ... +2. Shared visibility: personal / shared + +Four orthogonal combinations the user had to mentally assemble: +- Personal scope + personal visibility = "just me, no team" +- Personal scope + shared visibility = doesn't quite make sense (no team to share with) +- Team scope + personal visibility = "team-scoped but only I see it" +- Team scope + shared visibility = "team-scoped and team-visible" (the typical sync intent) + +** The collapse + +One prompt where each candidate spells out the complete end-state: + +#+begin_example +Where does this view live? + [ Team: Engineering, visible to the team ] <- default when :team Engineering in filter + [ Personal, only I see it ] + [ Team: Engineering, only I see it ] + [ Team: Marketing, visible to the team ] + [ Team: Marketing, only I see it ] + ... + [ Cancel. ] +#+end_example + +Same logical surface (N teams × 2 visibility + 1 personal). One fewer modal moment. Meaningless combination (personal + shared) absent from the list. Default at the top per the existing most-common-on-top pattern. + +** What changed by the collapse + +- Two prompts went to one. Smaller stack of decisions to track. +- Each option is now self-explanatory. "Visible to the team" reads as the consequence, not the mechanism. +- The default conveys *what will happen*, not just *which radio button is selected*. +- The degenerate combination doesn't have to be defended against in code -- it's not in the candidate list. + +** Why for the catalog + +This is a third worked form of the principle that's emerging across the pearl catalog notes: + +#+begin_quote +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. +#+end_quote + +Previous catalog candidates touch parts of it: +- Pattern 3 (no empty input as meaningful): visible choices, no hidden idioms. +- Pattern 4 (prompt label matches behavior): accurate labels. +- Pattern 5 (default the most-common choice): right ordering, with safety-proportional friction. + +This pattern (collapse N orthogonal prompts into one enriched prompt) is the *cross-product* form. When two or more prompts compose, each combination IS its own meaningful choice, and the user thinks about end-states, not dimensions. So show the cross-product, label each row with its end-state, and let the user pick destination rather than coordinates. + +** Applicability gate + +The collapse only works when the cross-product is small enough to scan (5-20 rows comfortably). For N=2 dimensions × M values, that's 2M to N×M rows depending on whether all combinations are meaningful. + +It doesn't work when: +- The cross-product is large (many teams, many statuses, many priorities -- the candidate list becomes a wall). +- Dimensions are independently and frequently re-set (the user wants to change one without re-picking the rest). +- One dimension is "free text" (not a small enumerable set). + +For those cases the sequential-prompts shape stays appropriate. + +** Cumulative shape after this entry + +The pearl catalog now has six worked candidates: + +1. One-prompt picker with typed prefix (2026-05-27) +2. Transient state-buttons (Craig's external reference; magit-transient) +3. No empty input as meaningful (2026-05-28) +4. The prompt label matches what the prompt does (2026-05-28) +5. Default the most-common choice; friction sized to consequence (2026-05-28) +6. Collapse N orthogonal prompts into one enriched prompt (this note, 2026-05-28) + +Patterns 1, 3, 4, 5, 6 are arguably one principle in five shapes. The catalog might want a single root entry (the principle stated once) with five cross-linked worked examples; or six tightly-cross-linked separate entries. The single-principle-multiple-shapes form scans more cleanly as the count grows; six independent entries fragments the underlying idea. + +* Standing by + +Spec reviews welcome when the rulesets discussion produces a concrete shape. Pearl's docs/saved-query-sync-spec.org now sits at =Ready=; implementation can start whenever Craig says. diff --git a/docs/design/2026-05-28-pattern-catalog-prompt-labels-and-defaults.org b/docs/design/2026-05-28-pattern-catalog-prompt-labels-and-defaults.org new file mode 100644 index 0000000..cc2cb77 --- /dev/null +++ b/docs/design/2026-05-28-pattern-catalog-prompt-labels-and-defaults.org @@ -0,0 +1,69 @@ +#+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. -- cgit v1.2.3