@thebassclef/lite 1.0.3 → 1.1.0

package/dist/lite/.claude/luminaries/edward-tufte.md

@@ -0,0 +1,179 @@
+---
+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/dist/lite/.claude/luminaries/eric-evans.md

@@ -0,0 +1,160 @@
+---
+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/dist/lite/.claude/luminaries/frederick-brooks.md

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

package/dist/lite/.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.