@thebassclef/lite 0.0.1 → 0.1.0

package/substrate/.claude/luminaries/gang-of-four.md

@@ -0,0 +1,157 @@
+---
+tier: lite
+name: Gang of Four (Gamma, Helm, Johnson, Vlissides)
+slug: gang-of-four
+claimed_by: [builder]
+referenced_by_skills: [pattern-review, decompose, architect-review]
+primary_domain: engineering
+depth: full
+sources:
+  - type: book
+    title: "Design Patterns: Elements of Reusable Object-Oriented Software"
+    authors: ["Erich Gamma", "Richard Helm", "Ralph Johnson", "John Vlissides"]
+    year: 1994
+    url: "https://www.pearson.com/en-us/subject-catalog/p/design-patterns-elements-of-reusable-object-oriented-software/P200000009480"
+    isbn: "9780201633610"
+    methodology_covered:
+      - "23 named patterns across Creational, Structural, Behavioral categories"
+      - "Program to an interface, not an implementation"
+      - "Favor object composition over class inheritance"
+      - "Decorator for cross-cutting concerns; Strategy for algorithm variation; Observer for event propagation"
+      - "Pattern language as shared vocabulary for design discussion"
+verification_status: verified
+description: "\"Program to an interface, not an implementation."
+---
+
+# Gang of Four (GoF)
+
+## Signature
+
+*"Program to an interface, not an implementation. Favor object composition over class inheritance."*
+
+Authors of **Design Patterns: Elements of Reusable Object-Oriented
+Software** (1994). The bassclef reference for 23 named OO patterns
+across three categories (Creational, Structural, Behavioral). The
+book every serious engineer has read; the patterns every codebase
+implements, named or not.
+
+## Core methods
+
+### Creational patterns (how objects are made)
+- **Factory Method** — defer instantiation to subclasses
+- **Abstract Factory** — families of related objects
+- **Builder** — step-by-step complex construction
+- **Prototype** — clone existing instances
+- **Singleton** — one shared instance (use sparingly)
+
+### Structural patterns (how objects compose)
+- **Adapter** — translate one interface to another
+- **Bridge** — decouple abstraction from implementation
+- **Composite** — tree structures of uniform objects
+- **Decorator** — add behavior without subclassing (critical for
+  cross-cutting concerns — see `/decompose` Phase 3)
+- **Facade** — simplified interface to subsystem
+- **Flyweight** — share state for many small objects
+- **Proxy** — placeholder controlling access
+
+### Behavioral patterns (how objects collaborate)
+- **Chain of Responsibility** — pass request through handlers
+- **Command** — encapsulate request as object
+- **Interpreter** — language grammar evaluation
+- **Iterator** — sequential access without exposing structure
+- **Mediator** — reduce inter-object coupling
+- **Memento** — capture and restore state
+- **Observer** — notify dependents of state change
+- **State** — behavior varies by internal state
+- **Strategy** — algorithm varies at runtime
+- **Template Method** — skeleton with overridable steps
+- **Visitor** — operations over object structure
+
+## When to channel this luminary
+
+When the primary risk is reinventing solved structural problems badly.
+GoF dominates for Construction pattern selection, code review, and
+decomposition work. Pair with Fowler (enterprise patterns extend GoF),
+Uncle Bob (SOLID shapes how patterns apply), and Cockburn (Hexagonal
+Architecture places patterns in structural context).
+
+Do NOT channel GoF for: trivial code where no pattern applies,
+greenfield work where you should first ask whether the problem is
+really structural, or to justify over-engineering.
+
+## Stack translation
+
+In Next.js + React + TypeScript:
+
+- **Facade** → server actions composing multiple services for a single
+  operation (`app/actions/create-deal.ts`).
+- **Adapter** → `lib/adapters/[vendor].ts` wraps external APIs with
+  consistent interface.
+- **Strategy** → `IScoringStrategy` with multiple implementations;
+  registry selects at runtime.
+- **Decorator** → `ObservedImputer` wraps `IAssociationImputer` for
+  tracing; `CachedRepository` wraps `IRepository` for caching. THE
+  pattern for cross-cutting concerns per `/decompose` Phase 3.
+- **Observer** → React context + useEffect for subscription; Prisma
+  middleware for data-change events.
+- **Factory** → `createClient()` functions that return configured instances.
+- **State** → XState machines for complex UI state (deal-stage wizard).
+- **Template Method** → base classes with abstract steps (rare in
+  modern React; prefer composition).
+- **Proxy** → Next.js middleware for auth; SWR for cached API access.
+
+## Anti-patterns it prevents
+
+- **Pattern invention** — creating novel structural solutions to solved
+  problems. Results are always worse than the pattern.
+- **Pattern without need** — using Observer where a simple callback
+  works; Strategy where an if-statement works. Pattern overhead without
+  variation pressure.
+- **Mis-fit pattern** — applying a pattern whose preconditions don't
+  hold. Factory for simple `new` calls. Decorator for behavior that's
+  intrinsic (not cross-cutting).
+- **Pattern stacking** — using five patterns where two would suffice.
+  Each pattern has cognitive cost.
+- **Inheritance as default structural tool** — GoF's opening principle
+  is "favor composition over inheritance." Deep inheritance hierarchies
+  are usually wrong.
+
+## Worked example
+
+For POA's email-imputation facade (per `/decompose` Phase 3):
+
+GoF pattern selection:
+- **Facade**: `AssociationImputer` exposes simple interface, hides
+  LLM provider complexity
+- **Strategy**: Different providers (Haiku, Gemma) as interchangeable
+  implementations of `IAssociationImputer`
+- **Adapter**: `AnthropicAdapter`, `GeminiAdapter` wrap vendor SDKs
+  behind common interface
+- **Decorator**: `ObservedImputer` wraps any imputer with Langfuse
+  tracing — cross-cutting observability
+- **Proxy**: `CachedImputer` wraps any imputer with recent-result
+  caching — cross-cutting performance
+- **Chain of Responsibility** (future): multiple imputers in fallback
+  chain — Haiku first, Gemma on low confidence, human review on very
+  low confidence
+
+What GoF would NOT produce: one concrete `HaikuImputer` class with
+observability, caching, error handling, and provider logic all
+intertwined. That's the anti-pattern `/decompose` evolution was
+built to prevent.
+
+## Sources
+
+- *Design Patterns: Elements of Reusable Object-Oriented Software* —
+  Gamma, Helm, Johnson, Vlissides, Addison-Wesley (1994)
+- No primary website (the book is the source)
+
+## Related luminaries
+
+- **Robert C. Martin** — SOLID principles guide pattern application.
+- **Martin Fowler** — PoEAA extends GoF patterns to enterprise context.
+- **Erich Gamma** individually — co-author, later led VS Code.
+- **Christopher Alexander** — "A Pattern Language" (architecture, 1977)
+  inspired the software pattern movement.
+- **Head First Design Patterns** (Freeman, Robson) — accessible entry
+  to GoF for learners.

package/substrate/.claude/luminaries/jason-fried-dhh.md

@@ -0,0 +1,46 @@
+---
+tier: lite
+name: Jason Fried / DHH (David Heinemeier Hansson)
+slug: jason-fried-dhh
+claimed_by: [shaper]
+referenced_by_skills: [canvas, sprint]
+primary_domain: shaping
+depth: stub
+description: "\"It doesn't have to be crazy at work.\""
+---
+
+# Jason Fried / DHH
+
+## Signature
+
+*"It doesn't have to be crazy at work."*
+
+Basecamp founders; the philosophical foundation behind Shape Up. Canonical
+voices on **calm, independent, opinionated product work** — small teams
+shipping polished software on a rhythm, without the manufactured urgency
+of startup culture.
+
+## Core methods
+
+- **Appetite over estimation** (later operationalized by Singer as Shape Up) —
+  Fixed time, variable scope. Don't estimate; bet.
+- **Six-week cycles + two-week cool-down** — Deliberately slow cadence.
+  Reject agile theater of weekly sprints.
+- **Interruption is the enemy** — Long uninterrupted time is the actual
+  productivity multiplier. Meetings, chat, "quick syncs" destroy it.
+- **Opinionated software** — Products that make choices for users reduce
+  decision fatigue. Neutrality is a design failure.
+
+## Sources
+
+- *Rework* — Fried, Hansson, Crown Business (2010)
+- *It Doesn't Have to Be Crazy at Work* — Fried, Hansson, Harper Business (2018)
+- *Getting Real* — 37signals (2006), free online at gettingreal.37signals.com
+- basecamp.com/books — all 37signals/Basecamp books free
+
+## Related luminaries
+
+- **Ryan Singer** — Singer operationalized Fried/DHH's philosophy into
+  Shape Up; they are the underlying philosophy, he is the method.
+- **Catherine Wu (Anthropic)** — "Underfund on purpose" echoes Fried/DHH's
+  appetite discipline.

package/substrate/.claude/luminaries/jesse-james-garrett.md

@@ -0,0 +1,154 @@
+---
+tier: lite
+name: Jesse James Garrett
+slug: jesse-james-garrett
+claimed_by: [designer]
+referenced_by_skills: [ia-model, canvas, spec]
+primary_domain: ux
+depth: full
+sources:
+  - type: book
+    title: "The Elements of User Experience: User-Centered Design for the Web and Beyond (2nd edition)"
+    authors: ["Jesse James Garrett"]
+    year: 2010
+    url: "https://www.pearson.com/en-us/subject-catalog/p/elements-of-user-experience-the-user-centered-design-for-the-web-and-beyond/P200000009272"
+    isbn: "9780321683687"
+    methodology_covered:
+      - "Five planes of UX — Strategy, Scope, Structure, Skeleton, Surface"
+      - "Decisions sequence from abstract (strategy) to concrete (surface)"
+      - "Each plane constrains the next; clarity at one plane prevents thrashing at others"
+      - "Information architecture as a structural-plane concern, distinct from skeleton (wireframe) or surface (visual)"
+verification_status: verified
+solves_problems_brownfield:
+  - "Project mixes strategy, scope, structure, skeleton, and surface decisions in one conversation"
+  - "Surface decisions are over-determining structural choices in the existing UI"
+  - "Team can't agree on which decisions belong at which level"
+solves_problems_greenfield:
+  - "Starting a multi-surface product where the five planes should sequence design decisions"
+  - "Building a UX strategy that decomposes work into orderable layers from day one"
+  - "Planning a product where strategy precedes scope precedes structure precedes skeleton precedes surface"
+  - "Designing a multi-month product where UX governance needs explicit decision-tier vocabulary"
+anti_patterns:
+  - "Tactical UI fixes where the five planes is overhead"
+  - "Single-page or single-screen work"
+description: "\"Every user experience has five planes: strategy, scope, structure, skeleton, surface."
+---
+
+# Jesse James Garrett
+
+## Signature
+
+*"Every user experience has five planes: strategy, scope, structure, skeleton, surface. Skip one and the next collapses."*
+
+Co-founder of Adaptive Path; author of **The Elements of User Experience**.
+Coiner of **Ajax** (2005). The bassclef framework for thinking about UX
+as a layered set of decisions that must be made in sequence — each plane
+constrains the next.
+
+## Core methods
+
+- **The Five Planes of UX** — From bottom (abstract) to top (concrete):
+  - **Strategy** — user needs + product objectives. What success means.
+  - **Scope** — functional specifications + content requirements. What
+    the product contains.
+  - **Structure** — interaction design + information architecture. How
+    it's organized.
+  - **Skeleton** — interface design, navigation design, information
+    design. Where things are placed.
+  - **Surface** — sensory design (visual, auditory). How it looks and
+    feels.
+- **Bottom-up sequence** — Each plane must be resolved before the plane
+  above it. Surface decisions made before strategy produce pretty
+  products that serve no one.
+- **Plane consistency** — Decisions on one plane must cohere across that
+  plane. An app with two incompatible IAs (one by section, one by
+  feature) has a structure-plane failure.
+- **Abstract-to-concrete progression** — Planes move from invisible
+  decisions (strategy) to visible output (surface). A team skipping
+  straight to surface design has no grounding for why.
+
+## When to channel this luminary
+
+When the biggest risk is getting the layers out of sequence — jumping to
+visual design before structure is resolved, or committing to scope
+before strategy is clear. Garrett dominates in project planning and
+SDLC-flow work: ensuring the right decisions happen in the right order.
+Think: new-product definition, UX audits of existing products, pedagogy
+for designers or teams new to systematic UX.
+
+Do NOT channel Garrett for: tactical interaction design decisions (use
+Norman, Tidwell), object-modeling (use Prater), visual polish (use
+Lupton, Ive).
+
+## Stack translation
+
+Garrett's planes map directly onto the bassclef SDLC:
+
+- **Strategy plane** → `/canvas` (Thesis stage) + iteration bet framing
+- **Scope plane** → `/canvas` (Shape stage) + `/spec` + feature list
+- **Structure plane** → `/ia-model` + `/jtbd-tasks` + `/task-scenarios`
+- **Skeleton plane** → `/interaction-design` + `/decompose` (responsibility)
+- **Surface plane** → `/frontend-design` + `/visual-review` + design tokens
+
+The bassclef UX translation chain (JTBD → HTA → IA → Interaction Design)
+is Garrett's structure plane made operational. `/riff-prototypes`
+skips to skeleton/surface only when the lower planes are resolved.
+
+## Anti-patterns it prevents
+
+- **Surface-first design** — starting with visual mockups before
+  structure or scope is settled. Produces beautiful products that fail
+  strategy tests.
+- **Premature plane commitment** — locking visual design before
+  interaction design is complete. Forces structure decisions to fit
+  pre-made mockups.
+- **Plane-skipping** — jumping from strategy to surface, or scope to
+  skeleton. Missing planes leave load-bearing decisions implicit.
+- **Plane inconsistency** — a strategy plane that says "operator tool"
+  paired with a surface plane that says "consumer SaaS." Reveals
+  uncoordinated decisions.
+- **Deliverable confusion** — treating wireframes (skeleton) as final
+  design, or treating mockups (surface) as structure. Each plane has
+  its own deliverables and can't substitute.
+
+## Worked example
+
+For POA's deal pipeline feature planning, Garrett's five planes produce:
+
+1. **Strategy**: Operator needs efficient pipeline management; product
+   objective is reducing time-to-close. Success = X% faster deal
+   throughput.
+2. **Scope**: Functional = deal CRUD, stage transitions, broker
+   association, note logging, search, export. Content = deal types,
+   stage definitions, standard fields, extension fields.
+3. **Structure**: Interaction = stage-transition flow, note-logging
+   flow, broker-assignment flow. IA = object-first nav (Deals, Brokers,
+   Sellers) with facets (stage, source, age).
+4. **Skeleton**: List-detail pattern for deals; right-rail for
+   secondary info; sticky stage-progress at top of detail view;
+   collapsed sections for enrichment data.
+5. **Surface**: Design tokens (colors, typography, spacing); dense
+   table view; status chips per stage; hover states and transitions.
+
+Each plane's output is input to the next. Skipping directly from
+Strategy to Surface (shopping for a pretty template) would produce a
+product that looks great and serves no specific operator workflow.
+
+## Sources
+
+- *The Elements of User Experience: User-Centered Design for the Web
+  and Beyond* — Garrett, New Riders (1st ed 2002, 2nd ed 2010)
+- *"Ajax: A New Approach to Web Applications"* — Garrett, Adaptive
+  Path essay (2005) that coined the term
+- jjg.net — Garrett's primary site (maintains classic Elements diagram)
+
+## Related luminaries
+
+- **Sophia Prater** — OOUX lives at Garrett's structure plane. Not a
+  replacement; a specific method for that plane.
+- **Alan Cooper** — Goal-Directed Design operates across planes but
+  grounds in strategy (user goals) and scope (task lists).
+- **Peter Morville** — IA work is structure-plane; Morville + Garrett
+  pair naturally.
+- **Ellen Lupton** — Typography is surface-plane; don't invoke until
+  skeleton is resolved.

package/substrate/.claude/luminaries/john-ousterhout.md

@@ -0,0 +1,94 @@
+---
+tier: lite
+name: John Ousterhout
+slug: john-ousterhout
+claimed_by: [architect, reviewer, builder]
+referenced_by_skills: [pattern-review, decompose]
+primary_domain: engineering
+depth: stub
+sources:
+  - type: book
+    title: "A Philosophy of Software Design"
+    authors: ["John Ousterhout"]
+    year: 2021
+    edition: "2nd"
+    url: "https://web.stanford.edu/~ouster/cgi-bin/aposd.php"
+    isbn: "9781732102217"
+    methodology_covered:
+      - "Deep modules — small interface hiding complex implementation"
+      - "Complexity is incremental — small drips add up; resist each one"
+      - "Define errors out of existence — design APIs so error conditions cannot occur"
+      - "Comments encode design decisions the code itself cannot"
+      - "Strategic vs tactical programming — invest in design over short-term wins"
+      - "Information hiding — modules expose only what callers need; the rest stays internal"
+  - type: course
+    title: "Stanford CS 190 — Software Design Studio"
+    authors: ["John Ousterhout"]
+    year: 2018
+    url: "https://web.stanford.edu/class/cs190/"
+    methodology_covered:
+      - "Source course where the principles in A Philosophy of Software Design were developed and tested"
+verification_status: verified
+description: "\"Complexity is anything that makes software hard to understand or modify."
+---
+
+# John Ousterhout
+
+## Signature
+
+*"Complexity is anything that makes software hard to understand or modify. The goal of software design is to reduce complexity."*
+
+Stanford professor. Creator of the Tcl scripting language and Raft consensus protocol. Author of **A Philosophy of Software Design** (2018, 2nd ed 2021), the modern SENTINEL_bassclef_text on simplicity, deep modules, and complexity-as-incremental-drift. Pairs with Beck (TDD) and Fowler (refactoring tactics): Beck asks "is it tested?", Fowler asks "how do I restructure it?", Ousterhout asks "is it the right shape in the first place?"
+
+## Discipline anchor
+
+**Design judgment + complexity-as-enemy.** Ousterhout supplies the WHY-to-refactor framing that Beck and Fowler leave to the engineer's judgment.
+INSTEAD: Beck owns the red-green-refactor cycle; Fowler owns the catalog of refactorings; Ousterhout owns the design-quality lens that tells you whether the shape you're refactoring toward is actually better. Without this lens, refactors can shuffle complexity without reducing it.
+
+This luminary fires on architectural-judgment moments — picking module boundaries, naming interfaces, deciding whether to split a class, evaluating whether a comment is doing real work or restating the code.
+INSTEAD of citing Ousterhout for test mechanics, refactoring tactics, or pattern catalog selection: route those concerns to Beck, Fowler, and GoF respectively.
+
+## Key principles
+
+- **Deep modules** — A module is deep when it has a small interface and a large, complex implementation hidden behind it. Shallow modules push knowledge to callers and produce a system where understanding the whole requires understanding every part. When tempted to split a class for "smaller files," ask: does the split produce TWO deep modules, or TWO shallow ones?
+  INSTEAD of defaulting to file-size as the splitting metric: use interface-shape as the metric. Two deep modules from a split is a win; two shallow modules from a split is a regression even if the line count drops.
+
+- **Complexity is incremental** — Complexity accumulates one small decision at a time. A single special case, a single dependency, a single inconsistency feels harmless. Sum across a session, a release, a year — that's how systems become unmaintainable. The discipline is to resist each small drip rather than promise to clean up the puddle later.
+  INSTEAD of deferring cleanup to a future refactor: refuse the small drip at the moment it appears. Future-refactor cleanups almost never happen; the cost of resisting at write-time is the cheapest moment.
+
+- **Define errors out of existence** — Design APIs so error conditions cannot occur, rather than designing APIs that throw errors and asking every caller to handle them. The classic example: `unset` on a variable that does not exist is an error in older shells.
+  INSTEAD: the right shape is for `unset` to be idempotent. Applied to bassclef: hooks that BLOCK on missing artifacts are weaker than hooks that bootstrap the artifact when absent, where bootstrapping is safe.
+
+- **Comments encode design decisions code cannot** — Code says what it does. Comments must say what the code cannot — the WHY (invariant), the WHAT-IF (alternative considered and rejected), the WATCH-OUT (subtle constraint a future reader will miss).
+  INSTEAD of comments that restate code: write comments that record decisions. This principle is load-bearing for bassclef's `bassclef-configs.jsonc` discipline: inline comments are the adopter-discovery surface, not exhaust.
+
+## When to cite this luminary
+
+Cite `@luminary john-ousterhout` when:
+
+- **Reviewing module boundaries** (`/pattern-review`) — is this class deep or shallow? Would splitting it make two deep modules or two shallow ones?
+- **Decomposing responsibilities** (`/decompose` GRASP audit) — does each responsibility assignment produce a deep module, or push complexity to callers?
+- **Designing bassclef-configs.jsonc or other adopter-edit surfaces** — inline comments must encode WHY-to-pick and WHEN-to-pick, not restate the field name. This is "comments-as-design" applied to substrate configuration.
+- **Evaluating whether complexity is essential or accidental** — when a feature feels harder to ship than it should, ask whether the difficulty is in the problem domain (essential) or in how earlier decisions shaped the code (accidental). Accidental complexity is the refactor signal.
+
+When the question is test mechanics, refactoring step-by-step, design-pattern selection, distributed-systems scalability, or algorithmic complexity, route elsewhere.
+INSTEAD: cite Beck (test mechanics), Fowler (refactoring tactics), GoF (pattern selection), Kleppmann (Phase C, scalability anchor), Bentley (Phase C, Big-O practical discipline).
+
+## Composes with
+
+- **Kent Beck** — TDD makes deep modules testable. Tests verify that the interface is actually small; without tests, deep modules look the same as shallow ones from outside.
+- **Martin Fowler** — Refactoring tactics serve Ousterhout's design judgment. Fowler tells you HOW to extract a method; Ousterhout tells you WHETHER the extraction produces a deeper module or shuffles complexity.
+- **Gang of Four** — Design patterns are deep-module exemplars when applied well. The Decorator pattern is a deep module; the over-applied Visitor pattern is often shallow because it pushes traversal logic to callers.
+- **Michael Feathers** (bassclef luminary catalog) — Characterization testing makes it safe to refactor toward deeper modules in legacy code where the original boundaries are unclear.
+
+## Refs
+
+- bassclef#1036 — this luminary's filing ticket
+- bassclef#867 — anchor-luminary verification pattern (stub-tier shape this entry follows)
+- bassclef#1037 — sibling ticket; testing-tier-config primitive (Ousterhout's comments-as-design framing anchors the Tier 0 vs Tier 3 comment rules)
+- bassclef#478 — `@pattern` annotation discipline (analog for `@luminary` citation discipline)
+
+## Stub-to-full
+
+This is a stub entry per bassclef#867 verification pattern — frontmatter plus 4-section body grounded in primary source. Full body (worked examples in bassclef's own substrate, anti-patterns catalog, signature stack-translation paragraph) is deferred to a luminary-authoring follow-on bet.
+INSTEAD of blocking citation on full-body completion: the stub is sufficient for `/pattern-review` and `/decompose` to invoke the lens today; the full entry deepens worked examples in a later pass.

package/substrate/.claude/luminaries/karl-popper.md

@@ -0,0 +1,132 @@
+---
+tier: lite
+name: Karl Popper
+slug: karl-popper
+claimed_by: [architect, reviewer, closer]
+referenced_by_skills: [diagnose, architect-review, promote, state-a-problem]
+primary_domain: philosophy
+depth: full
+sources:
+  - type: book
+    title: "The Logic of Scientific Discovery"
+    authors: ["Karl R. Popper"]
+    year: 1959
+    original_year: 1935
+    url: "https://www.routledge.com/The-Logic-of-Scientific-Discovery/Popper/p/book/9780415278447"
+    isbn: "9780415278447"
+    methodology_covered:
+      - "Falsifiability as demarcation criterion for scientific claims"
+      - "Bold conjectures + severe tests as the actual method"
+      - "Verification is impossible; falsification is decisive"
+  - type: book
+    title: "Conjectures and Refutations: The Growth of Scientific Knowledge"
+    authors: ["Karl R. Popper"]
+    year: 1963
+    url: "https://www.routledge.com/Conjectures-and-Refutations-The-Growth-of-Scientific-Knowledge/Popper/p/book/9780415285940"
+    isbn: "9780415285940"
+    methodology_covered:
+      - "Knowledge grows by refutation, not confirmation"
+      - "Better theories forbid more; the more a theory forbids the better"
+      - "All observation is theory-laden; there is no view from nowhere"
+  - type: book
+    title: "The Open Society and Its Enemies"
+    authors: ["Karl R. Popper"]
+    year: 1945
+    url: "https://press.princeton.edu/books/paperback/9780691158136/the-open-society-and-its-enemies"
+    isbn: "9780691158136"
+    methodology_covered:
+      - "Piecemeal social engineering over utopian planning"
+      - "Institutions that expose leaders to falsification"
+      - "Critical rationalism as social discipline"
+verification_status: verified
+description: "\"Good tests kill flawed theories; we remain alive to guess again.\""
+---
+
+# Karl Popper
+
+## Signature
+
+*"Good tests kill flawed theories; we remain alive to guess again."*
+
+Austrian-British philosopher (1902-1994). Author of *The Logic of Scientific Discovery* (Hutchinson, 1935 German / 1959 English) and *Conjectures and Refutations* (1963). The bassclef voice on falsifiability, hypothesis testing, and the discipline that a claim which cannot be falsified is steering language, not truth.
+
+## Core methods
+
+- **Falsifiability as demarcation** — a claim is scientific to the extent that it can be shown wrong. Unfalsifiable claims may be inspiring; they are not knowledge. In substrate work: an assertion with no rebuttal cell is either a definition or an act of faith.
+- **Conjectures and refutations** — knowledge grows by making bold conjectures and then trying hard to break them. The bolder the claim, the more the world it forbids, the more informative it is when it survives testing.
+- **The severity of tests** — a test that could have refuted the claim but did not is severe. A test the claim was designed to pass is weak. Testing is not a formality; it is the entire epistemic engine.
+- **Piecemeal engineering** — for social + technical systems, small changes that can be reverted are better than sweeping redesigns that cannot. The value is not the change itself; it is the reversibility.
+- **All observation is theory-laden** — there is no raw data. Every observation runs through the framework the observer brings. This is why the warrant matters, not just the data.
+
+## When to channel this luminary
+
+When the primary risk is root-cause claims, cure recommendations, or diagnostic assertions shipping without stated conditions for being wrong. Popper dominates for `/diagnose` output (root-cause hypotheses), audit findings (severity claims), cure recommendations (why THIS cure, not another), and any assertion the operator will act on. Pair with Toulmin (Popper's rebuttal cell IS Toulmin's rebuttal cell) and Peirce (Peirce names the alternatives; Popper says test each).
+
+Pass-through cases (Popper adds no value):
+
+- Pure definition claims ("this is what we call X"). INSTEAD of falsification testing: preserve the definition; it is a naming act, not a knowledge claim.
+- Aesthetic preference statements. INSTEAD of falsification testing: preserve the preference; it is Peirce's pragmatic-maxim category, not Popper's.
+- Operator-authored directives. INSTEAD of falsification testing: honor the directive; operator preference is a starting point for inquiry, not a hypothesis to be falsified.
+
+## Stack translation
+
+In bassclef substrate work:
+
+- **`/diagnose` output** → hypothesis + falsification test. What repro would show the hypothesis is wrong? Write it before writing the fix.
+- **Audit finding severity** → what evidence would demote HIGH to MEDIUM? Name it. If nothing would demote it, the severity is either a definition or a decree.
+- **Cure recommendation** → what evidence would show this cure does not close the class? Name the test. If no test would falsify, the cure is faith not analysis.
+- **Turn estimate** → the estimate is a prediction. What actuals would falsify it? Grounding estimates in prior WU turn counts is Popper's discipline — the prior WUs are the tests the estimate survives.
+- **Root-cause claim** → the cause is the hypothesis. Removing it should remove the symptom. If removal does not remove the symptom, the cause was wrong. Test before shipping.
+
+## Anti-patterns it prevents
+
+- **Unfalsifiable severity** — "This is HIGH-severity because it matters." No evidence would demote it. Not a claim.
+
+  INSTEAD: state the criteria that would demote the finding. If none exist, the finding is a decree, not evidence.
+
+- **Root-cause attribution without repro** — "The cause is X" with no test that would show removing X does not remove the symptom.
+
+  INSTEAD: state the repro that would falsify. Run it. Ship the fix only after the test discriminates.
+
+- **Cure recommendation without a losing condition** — "This cure closes the class" with no criterion that would show it does not.
+
+  INSTEAD: state the observation that would show the class still reproduces after the cure. That IS the acceptance test.
+
+- **Confirmation-only diagnosis** — running only the test the hypothesis passes.
+
+  INSTEAD: run the severest test the hypothesis could survive. If it survives that, it is stronger than a test that was designed to pass.
+
+- **Sweeping redesign** — replacing a hook, a rule, or a substrate primitive with a cleaner version, all at once, no reversibility path.
+
+  INSTEAD: ship the smallest reversible change. Piecemeal engineering ships smaller changes with revert paths.
+
+## Worked example
+
+For a claim that a hook is dead-letter:
+
+Popper's discipline:
+
+- **Conjecture**: The hook `X.sh` is dead-letter — it exists on disk but is not wired in `.claude/settings.json`. Its checks do not fire.
+- **Severe test**: Deliberately trigger the condition the hook is supposed to catch. Author a file that violates the hook's stated rule; attempt to write it. If the write succeeds without the hook firing, the conjecture is confirmed. If the hook fires and blocks the write, the conjecture is falsified.
+- **Result**: Wrote the violating file. Write succeeded. No BLOCK message. The hook did not fire. Conjecture survives; hook is dead-letter.
+- **What would falsify**: A BLOCK message appearing in the write attempt. It did not appear.
+
+Without Popper's discipline the diagnosis would read "the hook seems broken" — no test, no falsification criterion, no way to distinguish "actually broken" from "I did not trigger it right." INSTEAD: state the conjecture, name the severe test, run it, report the result.
+
+## Sources
+
+- *The Logic of Scientific Discovery* — Popper, Hutchinson (1935 German original; 1959 English translation; Routledge reprint)
+- *Conjectures and Refutations: The Growth of Scientific Knowledge* — Popper, Routledge (1963)
+- *The Open Society and Its Enemies* — Popper, Routledge (1945; Princeton reissue 2020)
+- *Objective Knowledge: An Evolutionary Approach* — Popper, Oxford University Press (1972)
+- Stanford Encyclopedia of Philosophy: entry on Popper — plato.stanford.edu/entries/popper/
+
+## Related luminaries
+
+- **Stephen Toulmin** — Toulmin's argument model gives the shape (claim/data/warrant); Popper sharpens the rebuttal cell. A Toulmin argument without the rebuttal cell is a Popperian pseudo-claim. Both ship in bet 2026-07-01b WU-2.
+- **Charles Sanders Peirce** — Peirce's abductive reasoning names multiple hypotheses; Popper says test each one severely. Peirce fills the alternatives; Popper says which alternative survives. Both ship in bet 2026-07-01b WU-2.
+- **W. Edwards Deming** — Deming's PDCA cycle is Popper's conjecture-and-refutation applied to management. Plan (conjecture), Do (test), Check (see if the test broke the plan), Act (revise).
+- **Michael Feathers** — Feathers' characterization tests are severe tests for legacy code. Without characterization tests, refactoring is unfalsifiable — no test would show the refactor broke behavior.
+- **Kent Beck** — Beck's TDD is Popper at the code layer. The red test is the severe test the claim must survive to become green. TDD without a red step is unfalsifiable design.
+
+Anchors `.claude/rules/assert-only-after-verify.md` alongside Toulmin + Peirce. Primary luminary for `/diagnose` skill in root-cause hypothesis testing.