aboutsummaryrefslogtreecommitdiff
path: root/claude-rules/patterns.md
diff options
context:
space:
mode:
authorCraig Jennings <c@cjennings.net>2026-06-05 00:55:21 -0500
committerCraig Jennings <c@cjennings.net>2026-06-05 00:55:21 -0500
commit83bf3cb50c88f91730656a2242141567551063ac (patch)
tree069f0d9d52ac6ffe9c4a97a770be460b01e75cd5 /claude-rules/patterns.md
parent3eed2895b2d23d1d8e468aee6f3dfd8122012fe4 (diff)
downloadrulesets-83bf3cb50c88f91730656a2242141567551063ac.tar.gz
rulesets-83bf3cb50c88f91730656a2242141567551063ac.zip
feat(patterns): add cross-project pattern catalog (six seed patterns)
A good interaction-design pattern surfaces in one project, then gets lost, so the next project re-derives it. Pearl shipped six worked examples and the principle they share, but they sat as four raw notes in docs/design/ with nothing making them reusable. I added a patterns/ directory, one file per pattern, each with frontmatter (name, principle, problem, tags, source, examples) and a Problem / Do / Anti-pattern / Applicability / Related body. The six seeds: one-prompt-picker-typed-prefix, transient-state-buttons, no-empty-input-as-meaningful, label-matches-behavior, default-most-common-friction-proportional, collapse-orthogonal-prompts. Patterns 3-6 cross-link as facets of one root principle: 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. The catalog lives in rulesets because every project's agent already pulls from here. A thin claude-rules/patterns.md pointer tells the agent the catalog exists and when to consult it, so it reads one pattern on demand instead of carrying all of them. The pointer auto-installs via the Makefile RULES glob. README.org holds the root principle, the frontmatter contract, and the capture-on-landing/promote-on-review intake cadence. The patterns are .org files with #+KEYWORD frontmatter. The pointer stays .md because the rules layer and the Makefile glob require it. Seed patterns keep their concrete Elisp examples. Generalize on the second caller, not up front.
Diffstat (limited to 'claude-rules/patterns.md')
-rw-r--r--claude-rules/patterns.md29
1 files changed, 29 insertions, 0 deletions
diff --git a/claude-rules/patterns.md b/claude-rules/patterns.md
new file mode 100644
index 0000000..e079a28
--- /dev/null
+++ b/claude-rules/patterns.md
@@ -0,0 +1,29 @@
+# Pattern Catalog Pointer
+
+Applies to: `**/*`
+
+A curated catalog of reusable interaction-design patterns lives at `~/code/rulesets/patterns/`. Each pattern is one file capturing a small principle with wide surface area — discovered in one project, written down so the next project doesn't re-derive it.
+
+## When to consult it
+
+Before designing any user-facing interaction choice, read the relevant pattern instead of reinventing the shape:
+
+- A prompt or a chain of prompts (a completing-read, a wizard, a multi-step form)
+- A picker over N candidates where the kind of candidate matters, not just the name
+- A default for a yes/no or multiple-choice prompt
+- A confirmation whose friction should match its consequence
+- Any "should this be one prompt or several?" decision
+
+These patterns came out of Emacs/Elisp prompt design, but the principles are interface-general — they apply to a CLI flow, a web form, or a TUI just as well.
+
+## How to load it
+
+Don't carry the whole catalog in context. Read `~/code/rulesets/patterns/README.org` for the index and the one-line principle of each pattern, then read the single pattern file you need (the patterns are `.org` files). Humans grep `patterns/` directly.
+
+## The root principle
+
+The patterns converge on one idea: 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. Each pattern file is one worked shape of that principle.
+
+## Adding to it
+
+A new pattern is captured as a raw note in a project's `docs/design/` when it lands, then promoted into `patterns/` in a batched review (see `patterns/README.md` for the cadence and the frontmatter contract). Don't formalize every rough note inline — capture on landing, promote on review.