@thebassclef/lite 0.1.3 → 1.0.1

package/substrate/.claude/luminaries/don-norman.md

@@ -1,173 +0,0 @@
----
-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.

package/substrate/.claude/luminaries/edward-tufte.md

@@ -1,179 +0,0 @@
----
-tier: lite
-name: Edward Tufte
-slug: edward-tufte
-claimed_by: [creative-director, designer]
-referenced_by_skills: [frontend-design, visual-review, prototype-variants]
-primary_domain: visual
-depth: full
-sources:
-  - type: book
-    title: "The Visual Display of Quantitative Information (2nd edition)"
-    authors: ["Edward Tufte"]
-    year: 2001
-    url: "https://www.edwardtufte.com/tufte/books_vdqi"
-    isbn: "9781930824133"
-    methodology_covered:
-      - "Data-ink ratio — maximize the ink that represents data; minimize non-data ink"
-      - "Chartjunk — non-data ink that obscures rather than clarifies"
-      - "Lie factor — visual representation should match the underlying data scale"
-      - "Small multiples — series of small similar graphs for comparison"
-  - type: book
-    title: "Envisioning Information"
-    authors: ["Edward Tufte"]
-    year: 1990
-    url: "https://www.edwardtufte.com/tufte/books_ei"
-    isbn: "9780961392116"
-    methodology_covered:
-      - "Escaping flatland — representing multiple dimensions in two-dimensional space"
-      - "Color as data + micro-macro readings + layering and separation"
-  - type: book
-    title: "Visual Explanations: Images and Quantities, Evidence and Narrative"
-    authors: ["Edward Tufte"]
-    year: 1997
-    url: "https://www.edwardtufte.com/tufte/books_visex"
-    isbn: "9780961392123"
-    methodology_covered:
-      - "Visualizing causality and change over time"
-      - "Smallest effective difference — use the minimum visual difference that conveys the distinction"
-  - type: book
-    title: "Beautiful Evidence"
-    authors: ["Edward Tufte"]
-    year: 2006
-    url: "https://www.edwardtufte.com/tufte/books_be"
-    isbn: "9780961392178"
-    methodology_covered:
-      - "Sparklines — word-sized graphics embedded in running text"
-      - "Evidence presentation principles for analytical writing"
-verification_status: verified
-solves_problems_brownfield:
-  - "UI shows many numbers or trends in compressed space and legibility is breaking down"
-  - "Dashboard has accumulated decoration and chart-junk; signal is buried"
-  - "Multi-dimensional data displays are letting one dimension drown out others"
-  - "Users decode the chart before understanding the message"
-solves_problems_greenfield:
-  - "Planning a dashboard, financial report, or analytics UI that must show dense data clearly from day one"
-  - "Designing a surface where multiple quantitative dimensions need to coexist without one drowning the others"
-  - "Building a tool for domain experts who read data faster than narrative"
-  - "Need small multiples or sparklines as the main display element in the new design"
-anti_patterns:
-  - "Sparse, narrative-heavy surfaces — Tufte over-compresses"
-  - "Consumer-emotional or marketing surfaces — Tufte reads as cold"
-  - "First-time onboarding flows — density assumes domain familiarity"
-description: "\"Above all else, show the data. Maximize the data-ink ratio; every pixel that doesn't represent information is a candidate for removal.\""
----
-
-# Edward Tufte
-
-## Signature
-
-*"Above all else, show the data. Maximize the data-ink ratio; every pixel that doesn't represent information is a candidate for removal."*
-
-Yale statistician and visual communication theorist; author of **The
-Visual Display of Quantitative Information** (1983). The bassclef
-voice on data visualization — the standard against which all chart,
-dashboard, and data-dense UI work is measured.
-
-## Core methods
-
-- **Data-ink ratio** — The ratio of "ink" (visual weight) representing
-  actual data to total ink on the page. Maximize it. Every gridline,
-  axis label, border, or color swatch that doesn't represent data is a
-  candidate for removal.
-- **Small multiples** — Many small versions of the same chart, aligned
-  in a grid, enable comparison at a glance. A single complex chart
-  often reads better as 12 small simple ones.
-- **Sparklines** — Word-sized, intense, simple graphics embedded in
-  prose or tables. Show trend without dominating layout.
-- **Chartjunk elimination** — Cross-hatching, 3D effects, decorative
-  borders, grid backgrounds, redundant legends. All candidates for
-  removal. Most "business graphics" are majority chartjunk.
-- **Layering + separation** — Show multiple dimensions in the same
-  visualization through layers (color, line weight, opacity) that
-  separate clearly rather than blend into noise.
-- **Graphical integrity** — No distortion through truncated axes,
-  misleading scales, decoration that implies precision where none
-  exists. Graphics should reveal truth, not obscure it.
-
-## When to channel this luminary
-
-When the product is data-dense and the primary risk is that information
-will be decoration rather than communication. Tufte dominates for
-dashboards, analytics surfaces, financial tables, comparison views,
-time-series data, geographic data. Pair with Lupton for the typographic
-layer of the same dense surfaces.
-
-Do NOT channel Tufte for: brand-forward surfaces where information
-density is secondary (use Scher, Ive, Rams), narrative or editorial
-content (Lupton, Bierut), or playful/delightful experiences (Walter,
-Walsh).
-
-## Stack translation
-
-In React with chart libraries (Recharts, Visx, D3):
-
-- **Data-ink** → strip default gridlines, axis decorations, plot
-  borders. Add back only what's needed.
-- **Small multiples** → CSS grid of many small charts, shared axis,
-  consistent scale. `grid-cols-4` of 12 charts beats one giant chart.
-- **Sparklines** → inline SVG components in table cells; no axis,
-  minimal color, 40-80px wide by 20px tall.
-- **No chartjunk** → remove Recharts/Chart.js defaults (legends,
-  gridlines, tooltips) and add back only what's essential.
-- **Integrity** → axis starts at zero for magnitude charts; don't
-  truncate. Use log scale explicitly and label it. Never stack areas
-  to imply a total that isn't.
-
-## Anti-patterns it prevents
-
-- **3D charts** — three-dimensional representation of 2D data. Adds
-  nothing; distorts everything.
-- **Pie charts with many slices** — humans compare bar lengths better
-  than angles. Convert to horizontal bar chart.
-- **Decorative dashboards** — dashboards that prioritize visual
-  impressiveness over information density. Colors without meaning,
-  gauges without data, sparklines as ornament.
-- **Too many axes** — dual-axis charts overlaid without clear
-  separation. Viewer can't parse which line belongs to which axis.
-- **Chart redundancy** — the same number shown as a card, in a chart,
-  and in a table on the same screen. Pick one.
-- **Default library output** — shipping a Recharts chart without
-  styling it. Defaults are chartjunk; strip them.
-
-## Worked example
-
-For POA's deal-pipeline dashboard:
-
-Tufte's approach:
-- **Summary metrics**: large numbers in typographic weight, no
-  background cards, minimal chrome. "42 deals / $18M pipeline /
-  Q2 close rate 34%."
-- **Stage progression**: small-multiples of each stage's deal count
-  over time (6 small line charts in a row, shared time axis).
-- **Deal table**: dense, many rows visible, sparklines in the "age"
-  column showing days-in-current-stage.
-- **Colors**: only where they encode data (stage color, alert state).
-  No decorative colors.
-
-What Tufte would NOT produce: a dashboard with 3D bar charts, gauge
-widgets, "funnel" visualizations with decorative gradients, animated
-transitions that slow comprehension, or sidebars of big colored cards
-that display single numbers with excessive chrome.
-
-## Sources
-
-- *The Visual Display of Quantitative Information* — Tufte, Graphics
-  Press (1983, rev. 2001) — foundational text
-- *Envisioning Information* — Tufte (1990)
-- *Visual Explanations* — Tufte (1997)
-- *Beautiful Evidence* — Tufte (2006)
-- edwardtufte.com — primary site
-
-## Related luminaries
-
-- **Ellen Lupton** — Lupton + Tufte pair for data-dense typographic
-  surfaces. Tufte's data-ink, Lupton's type hierarchy.
-- **Dieter Rams** — Shared restraint philosophy; Rams in physical
-  objects, Tufte in information displays.
-- **Jony Ive** — Shared obsessive precision; Tufte at the data layer,
-  Ive at the material layer.

package/substrate/.claude/luminaries/eric-evans.md

@@ -1,160 +0,0 @@
----
-tier: lite
-name: Eric Evans
-slug: eric-evans
-claimed_by: [architect]
-referenced_by_skills: [architect-review, decompose, ia-model]
-primary_domain: architecture
-depth: full
-sources:
-  - type: book
-    title: "Domain-Driven Design: Tackling Complexity in the Heart of Software"
-    authors: ["Eric Evans"]
-    year: 2003
-    url: "https://www.domainlanguage.com/ddd/"
-    isbn: "9780321125217"
-    methodology_covered:
-      - "Ubiquitous Language — single language shared by domain experts and developers"
-      - "Bounded Contexts — explicit boundaries within which a particular model is defined and applicable"
-      - "Aggregates + Aggregate Roots — clusters of associated objects treated as a unit for data changes"
-      - "Domain Events + Domain Services + Repositories + Factories"
-      - "Strategic Design — Context Mapping + relationships between bounded contexts"
-  - type: paper
-    title: "Domain-Driven Design Reference (definitions and pattern summaries)"
-    authors: ["Eric Evans"]
-    year: 2015
-    url: "https://www.domainlanguage.com/ddd/reference/"
-    methodology_covered:
-      - "Free reference document — distilled DDD patterns and definitions"
-      - "Quick-lookup vocabulary for ubiquitous-language conversations"
-verification_status: verified
-description: "\"The model is the backbone of the design."
----
-
-# Eric Evans
-
-## Signature
-
-*"The model is the backbone of the design. Bounded contexts let multiple models coexist without collapsing into mud."*
-
-Author of **Domain-Driven Design** (the "blue book," 2003). The
-foundational voice on DDD — modeling complex domains through
-ubiquitous language, bounded contexts, and strategic design.
-
-## Core methods
-
-- **Ubiquitous Language** — the same vocabulary used by domain experts,
-  designers, and developers. Code names match business terms. "Deal"
-  in the model IS "Deal" in the code, not "Transaction" or "Record".
-- **Bounded Context** — an explicit boundary within which a particular
-  model applies. Multiple models can coexist (e.g., "Deal" in Acquisition
-  context vs "Deal" in Finance context) with documented translation
-  between them.
-- **Context Map** — the strategic view of how bounded contexts relate
-  (Partnership, Shared Kernel, Customer/Supplier, Conformist, Anticorruption
-  Layer, Published Language, etc.).
-- **Aggregates + Aggregate Roots** — cluster of domain objects treated
-  as a single unit for consistency. Root controls access; small
-  aggregates with references by ID between them.
-- **Entities vs Value Objects** — entities have identity that persists
-  across state changes; value objects are immutable and defined by
-  their attributes (Money, DateRange, Address).
-- **Domain Events** — things that happened in the domain worth
-  remembering (DealAdvanced, BrokerAssigned). Captured explicitly,
-  often drive integration between bounded contexts.
-
-## When to channel this luminary
-
-When the primary risk is domain complexity — multiple stakeholder
-viewpoints, technical jargon that hides business meaning, or
-schema-mirror code that ignores how the business thinks. Evans
-dominates for B2B products with specialist users, regulated domains,
-and enterprise integration work. Pair with Vernon (Implementing DDD —
-operational methods) always.
-
-Do NOT channel Evans for: CRUD apps with trivial domain logic,
-consumer products where user is not a specialist, or single-bounded-
-context systems small enough to model as one coherent whole.
-
-## Stack translation
-
-In Next.js + Prisma + TypeScript:
-
-- **Ubiquitous Language** → Prisma model names, TypeScript types, React
-  component names, URL paths all use the same domain vocabulary as the
-  business. No translation layer needed.
-- **Bounded Contexts** → separate domain directories under `lib/` per
-  bounded context (`lib/acquisition/`, `lib/finance/`), with explicit
-  mapping types at the boundary.
-- **Aggregates** → Prisma's nested transaction boundaries align with
-  aggregate roots. A single `prisma.$transaction` should map to one
-  aggregate's invariants, not cross aggregates.
-- **Value Objects** → TypeScript branded types for domain concepts
-  (`type DealId = string & { __brand: 'DealId' }`) prevent mixing.
-- **Domain Events** → Prisma middleware hooks or explicit event-dispatch
-  in services; events drive downstream integration.
-- **Anticorruption Layer** → adapters wrapping external APIs (enrichment
-  providers, email services) translate between their model and ours.
-
-## Anti-patterns it prevents
-
-- **Schema-mirror code** — code vocabulary that matches the database
-  table structure instead of the business domain. "UserDealJunction"
-  instead of "DealOwnership."
-- **Anemic Domain Model** — objects that hold data without behavior;
-  business logic scattered across services. Evans prefers rich
-  domain objects with behavior co-located with state.
-- **Big Ball of Mud** — one bounded context that tries to serve
-  every viewpoint. Acquisition logic mixed with reporting with
-  notifications all in one model.
-- **Transaction Script for non-trivial domains** — procedural code
-  orchestrating DB calls; fine for simple CRUD, breaks under
-  complex business rules.
-- **Linguistic leakage** — technical terms bleeding into business
-  communication ("let's persist the entity"). Ubiquitous Language
-  demands business vocabulary in both directions.
-
-## Worked example
-
-For POA's cross-module work (Acquisition + Communications + Reporting):
-
-Evans's approach:
-- **Three bounded contexts**, each with its own model:
-  - Acquisition: Deal, Seller, Buyer, Stage, Offer
-  - Communications: Thread, Message, Broker, Participant
-  - Reporting: DealSnapshot, StageAggregate, SourceMetrics
-- **Context Map** showing relationships:
-  - Acquisition → Communications: Customer/Supplier (Communications
-    consumes Deal events from Acquisition)
-  - Acquisition → Reporting: Published Language (Reporting reads
-    read-only snapshots, never mutates Acquisition)
-- **Ubiquitous Language per context** — a "Deal" in Acquisition is not
-  the same shape as a "DealSnapshot" in Reporting, and that's correct.
-- **Aggregates**: Deal is aggregate root in Acquisition; Thread is
-  aggregate root in Communications. They reference each other by ID.
-- **Domain Events**: `DealAdvanced` event fires from Acquisition, is
-  consumed by Communications (sends notifications) and Reporting
-  (updates aggregates).
-
-What Evans would NOT produce: one Prisma schema where User, Deal,
-Thread, and Report all share tables with "status" columns meaning
-different things in different views. That's the ball of mud he's
-explicitly preventing.
-
-## Sources
-
-- *Domain-Driven Design: Tackling Complexity in the Heart of Software* —
-  Evans, Addison-Wesley (2003) — THE foundational text
-- *Domain-Driven Design Reference* — Evans (2015, free PDF at domainlanguage.com)
-- domainlanguage.com — primary site
-
-## Related luminaries
-
-- **Vaughn Vernon** — Implementing DDD. Vernon operationalizes Evans
-  for teams new to DDD. Pair always.
-- **Martin Fowler** — Patterns of Enterprise Application Architecture
-  provides implementation vocabulary for DDD's strategic concepts.
-- **Alistair Cockburn** — Hexagonal Architecture contains bounded
-  contexts naturally; aggregates live inside hexagons.
-- **Gregor Hohpe** — EIP's integration patterns operate across
-  Evans's context map relationships.

package/substrate/.claude/luminaries/frederick-brooks.md

@@ -1,50 +0,0 @@
----
-tier: lite
-name: Frederick P. Brooks Jr.
-slug: frederick-brooks
-claimed_by: [orchestrator, architect]
-referenced_by_skills: [sprint, architect-review]
-primary_domain: orchestration
-depth: stub
-description: "\"Adding manpower to a late software project makes it later.\""
----
-
-# Frederick P. Brooks Jr.
-
-## Signature
-
-*"Adding manpower to a late software project makes it later."*
-
-Author of **The Mythical Man-Month** (1975, 1995). Canonical voice on
-**coordination costs, communication overhead, and why software projects
-fail at scale**. We invoke Brooks whenever the temptation is "throw more
-agents at it."
-
-## Core methods
-
-- **Brooks's Law** — Adding people to a late project makes it later.
-  Onboarding cost + communication overhead > productive output of new
-  hires for the duration of the delay.
-- **Communication overhead formula** — n people have n(n-1)/2
-  communication pathways. Coordination cost grows quadratically with team
-  size.
-- **No silver bullet** — No single development advance will improve
-  software productivity by an order of magnitude. Beware grand claims.
-- **Conceptual integrity over democratic design** — A single architect's
-  coherent vision beats a committee's compromise. Applies directly to
-  multi-agent orchestration: one coordinator, many executors.
-
-## Sources
-
-- *The Mythical Man-Month: Essays on Software Engineering* — Brooks,
-  Addison-Wesley (1975, 20th anniversary ed 1995)
-- *"No Silver Bullet — Essence and Accident in Software Engineering"* —
-  Brooks (1986)
-- Turing Award Lecture (1999)
-
-## Related luminaries
-
-- **Melvin Conway** — Conway's Law and Brooks's Law operate in the same
-  domain: organizational structure determines system structure and cost.
-- **Catherine Wu (Anthropic)** — "Underfund on purpose" is Brooks's
-  insight applied to agent orchestration: fewer agents, tighter scope.