docs: add cross-project pattern catalog spec

1 files changed, 49 insertions, 0 deletions

diff --git a/docs/design/2026-06-02-pattern-catalog-spec.org b/docs/design/2026-06-02-pattern-catalog-spec.org
new file mode 100644
index 0000000..e74b8ae
--- /dev/null
+++ b/docs/design/2026-06-02-pattern-catalog-spec.org
@@ -0,0 +1,49 @@
+#+TITLE: Cross-Project Pattern Catalog — Spec
+#+AUTHOR: Craig Jennings & Claude
+#+DATE: 2026-06-02
+
+One-page spec for capturing reusable design patterns so they travel from one project to the next instead of being re-derived. Drafted for Craig's spec-review; the five open questions from the [[file:../../todo.org][todo.org]] task carry a recommended call each, marked DECISION.
+
+* Problem
+
+Good interaction-design patterns get discovered in one project and then lost. Pearl shipped six worked examples (one-prompt picker with typed prefix, magit-transient state buttons, no-empty-input-as-meaningful, label-matches-behavior, default-most-common-with-friction-proportional-to-consequence, collapse-N-orthogonal-prompts-into-one) plus a synthesizing principle: "choices on screen, accurately labeled, ordered by what the user most often wants, friction sized to the cost of being wrong." Each is small with wide surface area. Today they live as four raw notes in =docs/design/=; nothing makes them reusable across projects, so every project re-derives them.
+
+Evidence base: [[file:2026-05-27-pattern-catalog-pearl-notes.org][2026-05-27]], [[file:2026-05-28-pattern-catalog-no-empty-input.org][no-empty-input]], [[file:2026-05-28-pattern-catalog-prompt-labels-and-defaults.org][prompt-labels-and-defaults]], [[file:2026-05-28-pattern-catalog-prompt-collapse.org][prompt-collapse]].
+
+* Design
+
+A curated catalog of patterns, one file per pattern, living where every project's agent already syncs from, surfaced to the agent by a thin pointer rule and discoverable by grep for humans.
+
+** DECISION 1 — Format: one file per pattern, with frontmatter
+
+Each pattern is its own file with structured frontmatter, not entries in a free-form doc. Fields: =name=, =principle= (one line), =problem= (what goes wrong without it), =do= (the pattern), =anti= (the failure mode it replaces), =examples= (links to real uses), =source= (where it was first articulated). Rationale: greppable, selectively loadable, stable metadata per pattern; a free-form doc stops scaling past ~10 patterns and can't be loaded a-pattern-at-a-time. Mirrors the shape of =memory/= and =claude-rules/=.
+
+** DECISION 2 — Home: the rulesets repo, a new =patterns/= directory
+
+The catalog lives in rulesets, the one place every project's agent already pulls from (=claude-rules=, =languages/=). That buys agent visibility everywhere for free. Linear is human-only and not agent-readable; per-project cross-links re-derive the same content. A dedicated =patterns/= directory keeps it out of =claude-rules/= (which loads wholesale every session — too heavy for a growing catalog).
+
+** DECISION 3 — Surfacing: agent-driven by default, human grep for free
+
+A thin =claude-rules/patterns.md= pointer tells the agent the catalog exists and when to consult it (designing a prompt flow, a picker, a default, any user-facing interaction choice). The agent reads the relevant pattern file on demand rather than carrying all of them in context. Humans grep =patterns/= directly. Lead with agent-driven because the whole point is that patterns reach the next project's build without Craig having to remember them.
+
+** DECISION 4 — Anti-patterns: included, as a field, not as separate entries
+
+Each pattern carries the failure mode it replaces in its =anti= field. A pattern without its anti-pattern is half-taught (same coaching logic as the review-code correction-explains rule). No standalone anti-pattern entries — they ride with the "do."
+
+** DECISION 5 — Intake cadence: capture-on-landing, promote-on-review
+
+When a pattern lands (a pearl handoff), the raw note drops into =docs/design/= as it does today. Promotion into the formal =patterns/= catalog happens in a batched review (folded into =task-audit= or a periodic pass), so the catalog stays curated instead of accreting every rough note. This matches what already happened — four notes accumulated, now being formalized in one pass.
+
+* Acceptance
+
+- =patterns/= directory exists in rulesets with the six seed patterns, each a file with the frontmatter fields above.
+- =patterns/README.org= (or =INDEX.org=) lists the catalog and states the frontmatter contract + the capture-on-landing/promote-on-review cadence.
+- =claude-rules/patterns.md= pointer rule tells the agent when to consult the catalog and how to load a single pattern.
+- The six seed patterns each cite their pearl-note source and at least one real example.
+- A consuming project's agent, designing a prompt flow, can find and apply the relevant pattern without re-deriving it.
+
+* Open questions for Craig
+
+- Directory name: =patterns/= vs =catalog/= vs under =claude-rules/=. Spec assumes =patterns/=.
+- Should the seed patterns be generalized beyond Emacs/Elisp framing (pearl is an Elisp project), or kept concrete with Elisp examples and generalized lazily? Spec leans concrete-now, generalize-on-second-use (mirrors the subagents "add the abstraction when the second caller arrives" rule).
+- Is a =/pattern= skill (add/promote a pattern interactively) worth it, or is a documented manual flow enough for now? Spec assumes manual flow first.