@thebassclef/lite 1.0.3 → 1.1.0

package/dist/lite/.claude/luminaries/charles-sanders-peirce.md

@@ -0,0 +1,150 @@
+---
+tier: lite
+name: Charles Sanders Peirce
+slug: charles-sanders-peirce
+claimed_by: [architect, reviewer, closer]
+referenced_by_skills: [diagnose, architect-review, promote, state-a-problem]
+primary_domain: philosophy
+depth: full
+sources:
+  - type: paper
+    title: "Deduction, Induction, and Hypothesis"
+    authors: ["Charles Sanders Peirce"]
+    year: 1878
+    url: "https://en.wikisource.org/wiki/Popular_Science_Monthly/Volume_13/August_1878/Illustrations_of_the_Logic_of_Science_VI"
+    methodology_covered:
+      - "Three modes of reasoning — deduction, induction, abduction"
+      - "Abduction as inference to the best explanation"
+      - "The role of hypothesis in scientific reasoning"
+  - type: paper
+    title: "How to Make Our Ideas Clear"
+    authors: ["Charles Sanders Peirce"]
+    year: 1878
+    url: "https://en.wikisource.org/wiki/Popular_Science_Monthly/Volume_12/January_1878/Illustrations_of_the_Logic_of_Science_II"
+    methodology_covered:
+      - "The pragmatic maxim — meaning is the practical consequences of belief"
+      - "Clarity through operational testing, not verbal definition"
+      - "Truth as the limit of inquiry over indefinite time"
+  - type: book
+    title: "Collected Papers of Charles Sanders Peirce (8 volumes)"
+    authors: ["Charles Sanders Peirce", "Charles Hartshorne (editor)", "Paul Weiss (editor)"]
+    year: 1931
+    original_year: 1866
+    url: "https://www.hup.harvard.edu/catalog.php?isbn=9780674138001"
+    isbn: "9780674138001"
+    methodology_covered:
+      - "Semiotics — the theory of signs and their interpretation"
+      - "Pragmatism as a philosophical method"
+      - "Logic of inquiry across science, ethics, aesthetics"
+verification_status: verified
+description: "\"Keep inquiry open.\""
+---
+
+# Charles Sanders Peirce
+
+## Signature
+
+*"Keep inquiry open."*
+
+American philosopher, logician, mathematician (1839-1914). Founder of pragmatism. Coined the term **abduction** — the mode of reasoning that names multiple hypotheses fitting the same evidence and then works to discriminate between them. The bassclef voice on alternative-consideration, root-cause diagnosis, and the discipline that one explanation for the data is rarely enough evidence.
+
+## Core methods
+
+- **Three modes of reasoning** — deduction (from rule + case to result), induction (from case + result to rule), and abduction (from result + rule to case). Only abduction generates new hypotheses. The others test what abduction proposes.
+
+  INSTEAD of running deduction alone: fire abduction first to generate the candidate set, then use deduction and induction to test each candidate.
+
+- **Abduction as inference to the best explanation** — when a surprising fact is observed, the abductive move is to ask "what would need to be true for this to be unsurprising?" Multiple candidates always fit.
+
+  INSTEAD of picking the first fit: name the candidates. Read source to discriminate.
+
+- **The pragmatic maxim** — the meaning of any belief is the practical consequences that follow if the belief were true. Beliefs whose truth or falsity make no operational difference are noise.
+
+  INSTEAD of arguing about beliefs that make no operational difference: reroute to a claim that has practical consequences the reader can test.
+
+- **Keep inquiry open** — the cardinal discipline in Peirce's epistemology. Any move that closes off alternative explanations before they have been tested is an inquiry-blocker. Confirmation bias is inquiry-blocking; committing to the first fit is inquiry-blocking.
+
+  INSTEAD of committing to the first fit: state the candidates, state the discrimination test, run the test.
+
+- **Truth as the long run** — truth is the limit of what inquiry would arrive at given indefinite time and effort. Individual claims are provisional; the community and the method carry the discipline.
+
+## When to channel this luminary
+
+When the primary risk is confirmation bias — committing to the first explanation that fits the data without considering alternatives. Peirce dominates for root-cause diagnosis, cure surface selection, audit method design, and any moment the agent surfaces "the cause is X" or "the cure is Y." Pair with Popper (Popper says which candidate survives severe testing; Peirce says name the candidates first) and Toulmin (Toulmin gives the argument shape; Peirce insists the claim cell name alternatives before committing).
+
+Pass-through cases (Peirce adds no value):
+
+- Single-choice technical decisions where only one option is technically feasible. INSTEAD of enumerating alternatives: preserve the one feasible option; abduction over a set of one is trivial.
+- Operator preference calls. INSTEAD of enumerating alternatives: honor the preference; the operator has already made the discrimination.
+- Trivial fixes where the failure message states the cause. INSTEAD of enumerating alternatives: preserve the stated cause; the compiler or test framework has already named the class.
+
+## Stack translation
+
+In bassclef substrate work:
+
+- **`/diagnose` root cause** → name 2-3 hypotheses that fit the repro. For each, name what would discriminate. Read source. Commit only to the one that survives.
+- **Cure surface selection** → the operator says "the class is R8." Peirce asks: what other classes could the same instances belong to? Confirmation bias would pick R8 because it is named; Peirce checks the alternatives before committing.
+- **Audit method** — the audit surfaces findings. Peirce asks: does the method's lens set exclude explanations by construction? A comprehension-side-only audit misses mechanism-fidelity findings because it lacks the lens. Naming the excluded class is Peirce's contribution.
+- **Ticket filing** — when filing a substrate-defect ticket, Peirce asks: what other tickets already name this class? Confirmation bias files a duplicate; Peirce reads the umbrella first.
+- **PR review** → for every "the cause is X" claim in the PR body, ask "what other causes would fit the same observation?" A PR that names only its own cause has skipped Peirce's discipline.
+
+## Anti-patterns it prevents
+
+- **One explanation without alternatives** — "The bug is caused by Y." Might be. Might be Z. Might be W. Naming three and picking one is the discipline.
+
+  INSTEAD: name 2-3 hypotheses that fit the same data. State the discrimination test. Run it.
+
+- **First-fit commitment** — the first hypothesis that fits gets the fix.
+
+  INSTEAD: test the second and third before shipping. The first fit is a candidate, not a conclusion.
+
+- **Blocked inquiry** — closing off an alternative because it is inconvenient, unfashionable, or would require re-reading source the agent has already skimmed.
+
+  INSTEAD: read the source again. Blocking inquiry is the cardinal sin in Peirce's frame.
+
+- **Inquiry theater** — naming three alternatives but designing the discrimination test to favor the preferred candidate.
+
+  INSTEAD: design the severe test (per Popper) and apply it to each alternative in turn.
+
+- **Meaningless distinctions** — arguing about beliefs that make no operational difference.
+
+  INSTEAD: apply the pragmatic maxim; if the belief has no practical consequence, reroute to a claim that does.
+
+## Worked example
+
+For a diagnostic surfaced during `/diagnose`:
+
+Peirce's shape:
+
+- **Surprising fact**: The kiss hook silent-fails under operator install.
+- **Candidate hypotheses**:
+  1. **H1**: The hook's path resolution uses SCRIPT_DIR/../../ which breaks under operator install layout.
+  2. **H2**: The hook is missing from operator's `~/.claude/settings.json` UserPromptSubmit matcher.
+  3. **H3**: The hook's install-class declaration is `project`, so it does not distribute to operator install.
+- **Discrimination**:
+  - Test H1: check the SCRIPT_DIR path under operator layout. Result: SCRIPT_DIR resolves; standards/ does not exist at ../../standards. H1 partially confirmed.
+  - Test H2: read `~/.claude/settings.json`. Result: hook IS wired. H2 falsified.
+  - Test H3: read hook header. Result: install-class: dual. H3 falsified.
+- **Conclusion**: H1 survives. Cure: use `resolve_standards_path` from `lib/hook-inject.sh` instead of SCRIPT_DIR/../../.
+- **Inquiry open**: H2 and H3 were tested even though H1 was the first fit.
+
+Without Peirce the diagnosis would read "the hook path is broken; fix the path." First-fit; the actual class (dual-install path resolution) stays hidden; the cure ships without the shared lib the class needs. INSTEAD: name three candidates, discriminate, ship the cure that survives.
+
+## Sources
+
+- "Deduction, Induction, and Hypothesis" — Peirce, *Popular Science Monthly* Volume 13 (August 1878)
+- "How to Make Our Ideas Clear" — Peirce, *Popular Science Monthly* Volume 12 (January 1878)
+- *Collected Papers of Charles Sanders Peirce* — Hartshorne + Weiss (eds.), Harvard University Press (1931-1935, 8 volumes)
+- *The Essential Peirce: Selected Philosophical Writings* — Nathan Houser + Christian Kloesel (eds.), Indiana University Press (Volume 1: 1867-1893; Volume 2: 1893-1913)
+- Stanford Encyclopedia of Philosophy: entry on Peirce — plato.stanford.edu/entries/peirce/
+- Stanford Encyclopedia of Philosophy: entry on abduction — plato.stanford.edu/entries/abduction/
+
+## Related luminaries
+
+- **Stephen Toulmin** — Toulmin's claim cell holds one claim; Peirce insists the claim be selected from a named set of alternatives. Toulmin plus Peirce is the well-shaped argument. Both ship in bet 2026-07-01b WU-2.
+- **Karl Popper** — Popper says test each hypothesis severely; Peirce says name the hypotheses to be tested. Without Peirce, Popper has nothing to falsify. Without Popper, Peirce's alternatives stay untested. Both ship in bet 2026-07-01b WU-2.
+- **Kaoru Ishikawa** — Ishikawa's fishbone diagram is Peirce's abduction with a shape. The six bones (Method, Machine, Material, Man, Measurement, Environment) prompt the agent to name candidates for each root-cause dimension before committing.
+- **Michael Feathers** — Feathers's characterization tests discriminate between hypotheses at the code layer. Peirce insists we name three; Feathers writes tests that show which one is right.
+- **W. Edwards Deming** — Deming's Act phase asks whether the intervention actually removed the defect; if not, the wrong hypothesis was the root cause. Peirce's abduction produces the candidates Deming's Act discriminates between.
+
+Anchors `.claude/rules/assert-only-after-verify.md` alongside Toulmin + Popper. Primary luminary for `/diagnose` skill in candidate-hypothesis enumeration.

package/dist/lite/.claude/luminaries/david-ogilvy.md

@@ -0,0 +1,192 @@
+---
+tier: lite
+name: David Ogilvy
+slug: david-ogilvy
+claimed_by: [designer, product-manager, creative-director, reviewer]
+referenced_by_skills: [ogilvy-writing-audit, kiss, journal, session-log]
+primary_domain: writing
+depth: full
+solves_problems_brownfield:
+  - "Prose reads dense or bureaucratic; readers bounce"
+  - "Memo asks for action but the ask is unclear"
+  - "Numbers and facts are dropped into the text without saying why they matter"
+  - "Bad news is buried in softening language; the reader has to decode"
+  - "Sentences run so long the reader loses the thread"
+solves_problems_greenfield:
+  - "Setting the writing voice for a new product surface"
+  - "Establishing a house style for chronicles, journal entries, or PR bodies"
+  - "Onboarding new writers to a plain-language discipline"
+  - "Drafting the first version of an ad, memo, or landing page"
+anti_patterns:
+  - "Corporate throat-clearing openers — 'Please be advised that,' 'It has come to my attention'"
+  - "Jargon used to sound important rather than to be precise"
+  - "Euphemisms that soften bad news into gibberish"
+  - "Facts presented alone with no interpretation"
+sources:
+  - type: archive
+    title: "David Ogilvy — 'How to Write' internal memo"
+    authors: ["David Ogilvy"]
+    year: 1982
+    url: "https://www.themarginalian.org/2012/02/07/david-ogilvy-on-writing/"
+    methodology_covered:
+      - "10 writing rules circulated to Ogilvy and Mather management"
+      - "Natural voice, short units, no jargon, verify quotations, read-aloud test, clear ask"
+  - type: book
+    title: "Writing That Works — How to Communicate Effectively in Business"
+    authors: ["Kenneth Roman", "Joel Raphaelson"]
+    year: 1981
+    url: ""
+    methodology_covered:
+      - "Comprehension — 'People seldom act on what they cannot understand'"
+      - "Completeness — 'When you say something, make sure you have said it'"
+      - "Honesty — no hedging, no euphemisms, straight talk on bad news"
+      - "Facts with context — no 'unstrung gems'"
+  - type: book
+    title: "Ogilvy on Advertising"
+    authors: ["David Ogilvy"]
+    year: 1983
+    url: ""
+    methodology_covered:
+      - "Copy discipline for headlines and body text"
+      - "Test-driven refinement of what actually sells"
+verification_status: verified
+description: "\"Write the way you talk. Naturally.\""
+---
+
+# David Ogilvy
+
+## Signature
+
+*"Write the way you talk. Naturally."*
+
+David Ogilvy (1911-1999) founded Ogilvy and Mather in 1948 and built the modern discipline of writing that persuades without pretense. His 1982 internal memo "How to Write" — ten rules circulated to Ogilvy and Mather management — remains the shortest useful writing style guide in publication. He paired it with a book he insisted every employee read three times: Kenneth Roman and Joel Raphaelson's *Writing That Works* (1981).
+
+## Core principle
+
+Prose is craft. Brevity, natural voice, and a clear ask beat every other lever. The reader is busy. The writer's job is to make the point easy to find and easy to act on.
+
+Three operational stances flow from this:
+
+1. **Write the way you talk.** Not casual. Not slang. Your natural voice speaking to a respected peer. Corporate throat-clearing ("Please be advised that") betrays the reader.
+2. **Every fact needs a reason it matters.** Numbers alone are unstrung gems. String them into an argument or drop them.
+3. **Bad news is not made better by burying it.** Honesty first. Sympathy second. Euphemisms make bad news worse by adding confusion.
+
+## What this looks like in Ogilvy and Mather
+
+- **Client memos read like conversation** — "I need a decision by Friday on whether to prioritize A or B" beats "It would be great if someone could weigh in on the priority question at their convenience"
+- **Ad headlines carry the whole ask** — the reader gets it from the headline; body text supports
+- **Facts always carry an "and therefore"** — a survey stat rides an interpretation
+- **Bad news arrives first** — "We're not going ahead with the campaign. Here's why"
+- **Read-aloud test before send** — if it stumbles in your mouth, it stumbles in the reader's
+
+## Core methods
+
+Six methods an agent can invoke by name during writing or review:
+
+- **Natural voice test** — Read the sentence aloud. Would a real person say it that way to a respected peer? INSTEAD of "Pursuant to our earlier discussion": "As we discussed."
+
+- **Short units test** — If a sentence runs past 25 words, split it. If a paragraph runs past 6 sentences, split it. Look for shorter words that mean the same thing: "utilize" becomes "use"; "commence" becomes "start."
+
+- **Read-aloud test** — Read the passage in your head. If it stumbles — tongue-twisters, awkward rhythms, no comma rest in a long line — rewrite until it flows.
+
+- **Completeness test** — Ask yourself: what is the ONE thing the reader needs to take from this? Is that thing actually written down, in plain language, somewhere the reader will see it? Roman and Raphaelson's warning: "When you say something, make sure you have said it. The chances of your having said it are only fair."
+
+- **Honesty test** — Are you saying what you mean or hiding behind softening language? Weasel words ("arguably," "somewhat," "perhaps"), euphemisms ("right-sizing," "we're going in a different direction"), passive voice hiding the actor ("mistakes were made") all fail.
+
+- **Facts-with-context test** — For every number, fact, or data point: does the reader know why it matters? Is it connected to a point? Roman and Raphaelson's metaphor: "Facts are building materials. Readers are not impressed by a pile of bricks. They want to see the building."
+
+## When to channel this luminary
+
+When the primary risk is **prose that fails to persuade or act on**. Ogilvy dominates any surface where an operator or adopter reads for a decision:
+
+- Chronicles and session logs — narrative record must land clearly
+- PR body Summary and Test plan sections — reviewers need the ask fast
+- Ticket bodies — Problem section must state user pain, not solution abstraction
+- Journal entries — external audience; Roman-and-Raphaelson completeness test essential
+- Turn prose in agent responses — operator scans on mobile; Ogilvy is exactly the frame
+- Marketing copy, landing pages, onboarding docs — the original domain
+
+Pair with **Rich Hickey** (simple vs easy at the writing shape layer — matches Ogilvy's short-units principle), **Stephen Toulmin** (argument shape underneath the words — Ogilvy's facts-with-context is Toulmin's warrant restated as writing craft), and **Kent Beck** (composition rhythm — Ogilvy's read-aloud test is TDD's red-green-refactor for prose).
+
+INSTEAD of channeling Ogilvy for pure technical documentation where precision beats natural voice (API contracts, schema shapes, error code tables): route to the surface's own discipline. Ogilvy applies to persuasive and narrative writing. Reference material has its own rules.
+
+## Stack translation
+
+Bassclef ships to operators and adopters. Both audiences read on mobile. Both bounce on friction. Ogilvy's discipline maps directly:
+
+| Ogilvy and Mather ad copy | Bassclef substrate output |
+|---|---|
+| Client memo asking for approval | PR body asking for review |
+| Ad headline that carries the whole ask | Ticket title + Problem section |
+| Body copy that supports the headline | Chronicle body + PR body Summary |
+| Bad news memo | Failed CI + incident report |
+| Read-aloud test before send | `/kiss words --grade10` + `/ogilvy-writing-audit` before commit |
+| Roman-and-Raphaelson three-times reading | `.claude/rules/writing-craft-discipline.md` auto-loaded every session |
+
+## Anti-patterns Ogilvy prevents
+
+- **Corporate throat-clearing openers.** "Please be advised that" adds distance. INSTEAD: state the point.
+- **Jargon to sound important.** "Leverage synergies across verticals" is worse than "get the teams talking." INSTEAD: use the plain word if it carries the same meaning.
+- **Bad news buried in sympathy.** "After careful consideration of a number of factors..." delays the point. INSTEAD: state the decision first, then the reason.
+- **Facts as unstrung gems.** "Revenue was 4.2M" without context does not persuade. INSTEAD: "Revenue was 4.2M, up 30 percent year over year — best quarter yet."
+- **Long sentences with no comma rest.** A 35-word sentence is physically hard to read aloud. INSTEAD: split at the natural clause boundary.
+
+## Worked example
+
+**Scenario.** Agent drafts a PR body Summary for a substrate change:
+
+**Before (fails Ogilvy — jargon + long sentences + buried ask):**
+
+> "Pursuant to the operationalized discussion of the load-bearing shape of the auto-save primitive, this PR introduces a cross-cutting refactor that leverages the SESSION_LOCK guard to obviate mid-session state pollution across a heterogeneous set of adopter operating environments."
+
+**After (passes Ogilvy — natural voice + short units + clear ask):**
+
+> "Bet 27a diagnose found that session-end.sh commits mid-session, polluting feature branches. This PR adds a SESSION_LOCK check before the commit. When an autonomous session is running, session-end.sh skips the commit. Existing tests stay green; three new cases cover the check. Reviewer confirms the Guard 0 block reads clearly."
+
+The second version reads at grade 7. Every sentence has a clear subject. Each idea gets its own sentence. The reader knows what the PR does and what to check.
+
+## How to apply
+
+When drafting operator-facing prose or reviewing draft output:
+
+1. **Ask: would a real person say this?** If not, rewrite in natural voice.
+2. **Ask: what is the ONE thing the reader needs to take from this?** Confirm it is actually written down in plain language.
+3. **Ask: for every fact or number, did I say why it matters?** If not, add the interpretation or drop the fact.
+4. **Read it aloud.** If it stumbles, rewrite.
+5. **Look for weasel words and euphemisms.** Swap for straight talk.
+6. **Check sentence length.** If any runs past 25 words, split.
+
+## How bassclef channels Ogilvy
+
+The discipline lives in:
+
+- `.claude/rules/writing-craft-discipline.md` — auto-loaded rule; adds Ogilvy tests as first-person composition checks
+- `standards/ogilvy-writing-rules.md` — reference standard with the 10 rules and violation patterns
+- `.claude/skills/ogilvy-writing-audit/SKILL.md` — operator-invocable audit skill; produces severity-tagged violations with specific fixes
+- `standards/bassclef-internal-jargon.md` — extended with Ogilvy business-jargon terms
+- `.claude/skills/kiss/SKILL.md` — cross-referenced; `/kiss words` composes with `/ogilvy-writing-audit` (audit diagnoses; kiss fixes)
+- `standards/skill-output-discipline.md` — extended to reference Ogilvy writing rules as the craft anchor
+
+## Related luminaries
+
+- **Rich Hickey** — simple vs easy at the writing shape layer. Ogilvy's short-units test is Hickey's discipline applied to sentences.
+- **Stephen Toulmin** — argument shape under the words. Ogilvy's facts-with-context is Toulmin's warrant restated as writing craft. The two pair naturally.
+- **Kent Beck** — composition rhythm. Ogilvy's read-aloud test is Beck's red-green-refactor for prose — write, read aloud, revise.
+- **Kenneth Roman and Joel Raphaelson** — Ogilvy insisted every Ogilvy and Mather employee read *Writing That Works* three times. R&R supply rules 7-10 (comprehension, completeness, honesty, facts-with-context) that Ogilvy's memo did not spell out. They stay paired throughout `standards/ogilvy-writing-rules.md`.
+- **Frederick Brooks** — conceptual integrity applies to prose voice. Ogilvy's discipline is one operator holding a coherent voice across every surface.
+
+## Sources
+
+- David Ogilvy — "How to Write" internal memo, September 7, 1982 (ten rules to Ogilvy and Mather management; still in wide circulation)
+- Kenneth Roman and Joel Raphaelson — *Writing That Works* (Harper and Row, 1981; Ogilvy insisted every employee read three times)
+- David Ogilvy — *Ogilvy on Advertising* (Crown, 1983)
+
+## Refs
+
+- Ticket #934 — this luminary's filing (Ogilvy skill + luminary + rule + standard)
+- Session 2026-07-27a chronicle — the operator + agent discussion that surfaced the fit
+- Sister rule `.claude/rules/plain-english-discipline.md` — bassclef's own grade-level rule that composes with Ogilvy's discipline
+
+## Retirement condition
+
+This luminary retires only if bassclef stops shipping operator-facing prose. Until then, Ogilvy is the writing-craft anchor for every surface where a human reads for a decision or a story.

package/dist/lite/.claude/luminaries/don-norman.md

@@ -0,0 +1,173 @@
+---
+tier: lite
+name: Don Norman
+slug: don-norman
+claimed_by: [designer]
+referenced_by_skills: [prototype-variants, interaction-design, visual-review]
+primary_domain: ux
+depth: full
+sources:
+  - type: book
+    title: "The Design of Everyday Things (revised and expanded edition)"
+    authors: ["Don Norman"]
+    year: 2013
+    url: "https://www.basicbooks.com/titles/don-norman/the-design-of-everyday-things/9780465050659/"
+    isbn: "9780465050659"
+    methodology_covered:
+      - "Affordances — what a thing tells you about how to use it"
+      - "Signifiers — perceivable signals of action possibilities"
+      - "Mapping — relationship between controls and their effects"
+      - "Feedback — communication of action results back to the user"
+      - "Conceptual models + mental models + system models"
+      - "Seven stages of action — bridge gulfs of execution and evaluation"
+  - type: book
+    title: "Emotional Design: Why We Love (or Hate) Everyday Things"
+    authors: ["Don Norman"]
+    year: 2004
+    url: "https://www.basicbooks.com/titles/donald-a-norman/emotional-design/9780465051366/"
+    isbn: "9780465051366"
+    methodology_covered:
+      - "Three levels of design — visceral + behavioral + reflective"
+      - "Emotion as integral to design quality, not decoration"
+  - type: book
+    title: "Living with Complexity"
+    authors: ["Don Norman"]
+    year: 2010
+    url: "https://mitpress.mit.edu/9780262528948/living-with-complexity/"
+    isbn: "9780262528948"
+    methodology_covered:
+      - "Complexity is necessary; complication is what we design against"
+      - "Signifiers carry the discipline that lets complex systems feel usable"
+verification_status: verified
+solves_problems_brownfield:
+  - "Users keep clicking the wrong thing or missing a button; affordances are unclear"
+  - "Interface error messages punish the user rather than help them recover"
+  - "Mental model and system model have diverged — users predict wrong outcomes"
+  - "Mode visibility is missing; users don't know what state they're in"
+solves_problems_greenfield:
+  - "Designing a new control surface where affordance language must be self-evident from first encounter"
+  - "Building a tool whose error model should help users recover, not punish"
+  - "Planning a product where mappings between control and effect must feel natural from day one"
+  - "Designing a system where visibility of state is a first-class concern"
+anti_patterns:
+  - "Designs whose primary value is delight or emotional resonance — Norman optimizes for clarity, not joy"
+  - "Highly abstract or conceptual UIs where direct manipulation isn't the model"
+description: "\"Good design makes the right action obvious."
+---
+
+# Don Norman
+
+## Signature
+
+*"Good design makes the right action obvious. The wrong action should be difficult, or at least conspicuously wrong."*
+
+Coined **user experience**; co-founder of Nielsen Norman Group; author of
+**The Design of Everyday Things** and **Emotional Design**. The bassclef
+voice on how physical and digital objects communicate their use through
+perceived properties.
+
+## Core methods
+
+- **Affordances** — What an object invites a user to do with it, based on
+  its physical/visual properties. A button affords pressing; a handle
+  affords pulling. The mismatch between real and perceived affordance is
+  a design failure.
+- **Signifiers** — Explicit clues that communicate what action is
+  possible. Where affordances are inherent, signifiers are designed.
+  Arrows, labels, shadows, highlights — all signifiers.
+- **Mapping** — The correspondence between controls and their effects.
+  A stove-top dial that controls the front-left burner should be
+  spatially closer to that burner than any other.
+- **Feedback loops** — Every action needs immediate, meaningful feedback
+  confirming what happened. Silent actions produce anxious users; long
+  delays produce retries and duplicate submissions.
+- **Constraints** — Physical, logical, semantic, cultural limits that
+  prevent wrong actions. A form field that rejects invalid characters
+  is a constraint; a confirmation dialog is not — it's a warning.
+- **Emotional design three-levels** — Visceral (initial impression),
+  behavioral (usability in use), reflective (meaning after use). All
+  three contribute to product success; missing any degrades the whole.
+
+## When to channel this luminary
+
+When the biggest risk is that users won't know how to use the thing —
+or will use it wrong. Norman dominates affordance-forward design:
+products where discoverability and error prevention at the interaction
+level are critical. Think: operator tools used daily, forms with
+financial or legal consequences, controls for complex processes where
+mistakes are expensive.
+
+Do NOT channel Norman as a primary for: content-heavy sites where
+structure dominates (use Prater or Morville), pure data visualization
+(Tufte), or identity work (Scher/Vignelli).
+
+## Stack translation
+
+In React + Tailwind + shadcn/ui:
+
+- **Affordances** → button components that look clickable (shadow,
+  hover state, cursor:pointer). Card components that don't look
+  clickable shouldn't be clickable.
+- **Signifiers** → explicit labels + icons + helper text. A disabled
+  button should show WHY it's disabled, not just dim.
+- **Mapping** → form layouts where the submit button is near the last
+  field, not floating in a sidebar. Navigation where the section you're
+  in is visually connected to its content.
+- **Feedback** → toast notifications, loading states, optimistic UI
+  updates. Every server action needs a returned state.
+- **Constraints** → form validation at field level (not just submit),
+  disabled states when actions are invalid, type="email" / type="number".
+
+## Anti-patterns it prevents
+
+- **Mystery meat navigation** — icons without labels; users guess what
+  each does. Norman's signifier principle demands explicit labeling.
+- **Hidden state actions** — buttons that do different things in
+  different states without signaling the change. Violates feedback
+  principle.
+- **Silent errors** — form submission that fails without communicating
+  why. Every error needs clear, actionable feedback at the point of
+  failure.
+- **Mode confusion** — UI that behaves differently in different modes
+  without clear mode indicators. The user doesn't know which mode
+  they're in.
+- **Ornamental affordance** — cards that look clickable but aren't;
+  elements styled like buttons but that are decorative. Betrays the
+  user's learned affordance expectations.
+
+## Worked example
+
+For a deal-stage transition control in POA:
+
+Norman would design it as: a clearly labeled button ("Advance to LOI"),
+visually grouped with the current stage display, disabled with
+explanation when the deal is missing required fields ("Missing: Offer
+Price, Buyer Contact"). On click: immediate loading state, optimistic
+UI showing the new stage, toast confirmation on server success, error
+banner with specific reason on failure ("Cannot advance: Seller hasn't
+signed NDA").
+
+What Norman would NOT produce: a stage dropdown with no explanation
+for why some options are grayed out; a silent state change where the
+deal advances without confirmation; a generic "Error" toast that
+doesn't explain what went wrong.
+
+## Sources
+
+- *The Design of Everyday Things* — Norman, Basic Books (1988, rev. 2013)
+- *Emotional Design: Why We Love (or Hate) Everyday Things* — Norman (2003)
+- *Living with Complexity* — Norman (2010)
+- jnd.org — Norman's primary site
+- Nielsen Norman Group — nngroup.com (co-founded)
+
+## Related luminaries
+
+- **Sophia Prater** — Prater works at the structural layer above Norman's
+  interaction layer. Use both: Prater for IA, Norman for the interactions
+  within each screen.
+- **Jenifer Tidwell** — Pattern library operationalizes Norman's
+  principles into reusable UI vocabulary.
+- **Jakob Nielsen** — NN/g co-founder; heuristics are Nielsen's
+  operationalization of Norman-adjacent principles.
+- **Aarron Walter** — Emotional design hierarchy builds on Norman's
+  three-level model.