@thebassclef/lite 1.1.0 → 1.2.0-alpha.1

package/dist/lite/.claude/hooks/session-reflection.sh

@@ -38,29 +38,69 @@ echo "$TIMING_NOW" > "$DURABLE_TIMING_DIR/${CWD_HASH}.timing" 2>/dev/null
 source "$(dirname "$0")/trace-helper.sh"
 trace_log "session-start" "$SOURCE"
 
-# Resolve bassclef dir through symlinks — used by modules to find scripts.
+# Resolve bassclef dir — cures sunj-labs/bassclef-cli#105 root cause.
+# Prior derivation walked up two levels from HOOK_REAL_PATH; under operator
+# install where the dispatcher lives at $HOME/.claude/hooks/, that resolved
+# to $HOME and 13 fragments read the wrong root. Now we probe four paths
+# via lib/bassclef-dir-resolver.sh — peer-checkout, $HOME/bassclef, bundled,
+# fallback to $CWD. See docs/decompositions/2026-09-18-phase-b-adopter-cures.md
+# for the GRASP + Ousterhout deep-module map.
 HOOK_REAL_PATH="$(readlink -f "$0" 2>/dev/null || readlink "$0" 2>/dev/null || echo "$0")"
-BASSCLEF_DIR="$(cd "$(dirname "$HOOK_REAL_PATH")/../.." && pwd)"
+{
+  _br_sd="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  for _br_c in "${_br_sd}/../../lib/bassclef-dir-resolver.sh" "${HOME:-/}/lib/bassclef-dir-resolver.sh"; do
+    [ -f "$_br_c" ] && source "$_br_c" && break
+  done
+  unset _br_sd _br_c
+} 2>/dev/null || true
+
+if declare -f resolve_bassclef_dir >/dev/null 2>&1; then
+  BASSCLEF_DIR="$(HOOK_REAL_PATH="$HOOK_REAL_PATH" CWD="$CWD" resolve_bassclef_dir)"
+else
+  # Defensive fallback if the resolver lib is not present. Preserves prior
+  # behavior; the cure still applies once the lib syncs into the adopter.
+  BASSCLEF_DIR="$(cd "$(dirname "$HOOK_REAL_PATH")/../.." && pwd)"
+fi
+export BASSCLEF_DIR
 
 # High-contrast BLOCKED banner; used by every module that raises a gap.
+# RFC-0008 F3 — "Silence is not deferral" is a commitment device. It works
+# because it forecloses the easy out, and it is consumable: spend it on a
+# check that turns out to be advice and the reader discounts it everywhere.
+# Callers that can prove their own state is benign pass a second argument
+# and get a softer close. Callers that pass one argument behave exactly as
+# before, so the other 27 sites are untouched.
 blocked_banner() {
   local msg="$1"
+  local severity="${2:-blocking}"
   echo ""
-  echo "🛑🛑🛑 BLOCKED 🛑🛑🛑"
-  echo "────────────────────────────────────────────"
-  echo "$msg"
-  echo "────────────────────────────────────────────"
-  echo "ACTION: resolve OR explicitly defer (per .claude/rules/blocked-items.md)."
-  echo "Silence is not deferral. Propose this as item #1 in your session plan."
+  if [ "$severity" = "advisory" ]; then
+    echo "NOTE"
+    echo "────────────────────────────────────────────"
+    echo "$msg"
+    echo "────────────────────────────────────────────"
+    echo "Worth doing. Not blocking this session."
+  else
+    echo "🛑🛑🛑 BLOCKED 🛑🛑🛑"
+    echo "────────────────────────────────────────────"
+    echo "$msg"
+    echo "────────────────────────────────────────────"
+    echo "ACTION: resolve OR explicitly defer (per .claude/rules/blocked-items.md)."
+    echo "Silence is not deferral. Propose this as item #1 in your session plan."
+  fi
   echo ""
 }
 
+# RFC-0008 F6 — this block is steering aimed at the agent, but the adopter
+# reads it too. Three imperatives and two shouted negations, before a single
+# check has run, read as "you already did something wrong". Say who it is
+# for, and say that it is state rather than a problem report.
 echo "============================================"
-echo "SESSION START — MANDATORY REFLECT → PLAN"
+echo "Session start — orientation"
 echo "============================================"
 echo ""
-echo "You MUST run the Session Start protocol before doing ANY other work."
-echo "Do NOT skip this. Do NOT jump to answering the user's question first."
+echo "Agent: work through this before answering. Reflect, then plan."
+echo "Reader: this is what the session found on disk, not a problem report."
 echo ""
 
 # === Last save state ===
@@ -112,10 +152,17 @@ if [ -f "$LOCK_FILE" ]; then
 fi
 
 # === Write session lock (AFTER checking — per standards/hook-idempotency.md) ===
-MACHINE=$(hostname -s 2>/dev/null || echo "unknown")
-echo "machine: $MACHINE" > "$LOCK_FILE"
-echo "timestamp: $(date +%Y-%m-%dT%H:%M:%S%z)" >> "$LOCK_FILE"
-echo "pid: $$" >> "$LOCK_FILE"
+# Guarded — silent skip when cwd has no .claude/ dir. A cold adopter (Sam)
+# opening Claude Code in a non-bassclef-onboarded cwd should not see a
+# visible shell error at first turn. Bassclef-onboarded cwds always have
+# .claude/ so behavior there is unchanged. Regression guard: adopter-simulator
+# T6 + T7 pin this contract.
+if [ -d .claude ]; then
+  MACHINE=$(hostname -s 2>/dev/null || echo "unknown")
+  echo "machine: $MACHINE" > "$LOCK_FILE"
+  echo "timestamp: $(date +%Y-%m-%dT%H:%M:%S%z)" >> "$LOCK_FILE"
+  echo "pid: $$" >> "$LOCK_FILE"
+fi
 
 # === Fetch origin before staleness checks (bassclef-upstream#403) ===
 # Several session-reflection.d/ fragments read git log / file listings

package/dist/lite/.claude/hooks/tool-failure-diagnosis.sh

@@ -0,0 +1,50 @@
+#!/bin/bash
+# tier: lite
+set -e
+
+# Tool Failure Diagnosis — fires on PostToolUse.
+# When a tool returns an error or failure signal, inject the
+# temperance → diagnose chain before Claude retries.
+
+INPUT=$(cat)
+# Fail-soft on malformed JSON — same pattern as bassclef#1101 pre-commit-gate
+# and bassclef#1119 post-write-trace. 3rd hook in /longrun-c with this bug.
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null || echo "")
+OUTPUT=$(echo "$INPUT" | jq -r '.tool_output // ""' 2>/dev/null | head -20 || echo "")
+
+# Check if the tool output contains failure signals
+if echo "$OUTPUT" | grep -qiE '(error|Error|ERROR|fail|FAIL|exit code [1-9]|ENOENT|EACCES|EPERM|denied|refused|404|500|502|503|504|panic|fatal|FATAL|exception|Exception|timed.out|no space|cannot|Could not|not found|Not Found|unhandled|Unhandled)'; then
+  SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+  source "$SCRIPT_DIR/trace-helper.sh"
+  trace_log "tool-error" "$TOOL_NAME failed"
+  cat <<'DIAG'
+============================================
+TOOL ERROR — TEMPERANCE → DIAGNOSE
+============================================
+
+A tool call just returned an error. Follow this chain:
+
+1. TEMPERANCE (pause before reacting)
+- Am I about to brute-force a retry with different args?
+- What is the SIMPLEST correct next step?
+- If I don't know WHY it failed, the answer is ALWAYS "understand first."
+
+2. DIAGNOSE (understand before fixing)
+- What failed: [tool, command, expected vs actual]
+- Is / Is Not: [what's broken vs what still works]
+- Why (quick trace): [1-3 whys to likely root cause]
+- Hypothesis: [what you think caused it]
+- Next step: [a READ-ONLY diagnostic command, NOT a fix]
+
+3. THEN FIX (only after diagnosis is written)
+
+For simple, expected errors (e.g., "file not found" when checking if
+something exists), state "Expected error — [reason]" and proceed.
+
+For unexpected errors: do NOT retry, do NOT guess different args,
+do NOT work around silently. Diagnose first.
+============================================
+DIAG
+fi
+
+exit 0

package/dist/lite/.claude/luminaries/andrej-karpathy.md

@@ -0,0 +1,165 @@
+---
+tier: lite
+name: Andrej Karpathy
+slug: andrej-karpathy
+claimed_by: [builder, architect, orchestrator]
+referenced_by_skills: []
+primary_domain: engineering
+depth: full
+sourcing_format: talk-and-post
+sourcing_note: "Karpathy's methodology lives primarily in conference talks, X / Twitter threads, blog posts, and Stanford lecture videos. Books are absent by design; the methodology evolves with the field and Karpathy publishes in the medium where the field actually lives. This differs from the catalog's book-based norm; accepted because book-based sourcing would misrepresent where this methodology is actually authored."
+solves_problems_brownfield:
+  - "Skills + agents + hooks fill context without a coherent budget — context window overflows or starves model decision-making"
+  - "Prompt design treated as ad-hoc text editing rather than as program design for a stateless compute engine"
+  - "Multi-agent dispatch leaks context across roles because agents are not modeled as stateless invocations needing explicit context threading"
+  - "Operator treats LLM as persistent service — model 'remembers' last conversation — and substrate decisions break under that mental model"
+solves_problems_greenfield:
+  - "Designing a substrate that explicitly allocates the context window across instruction + example + data + output budget per skill"
+  - "Choosing what state to persist (in markers + chronicles + state spine) versus what to re-derive per invocation"
+  - "Building agent choreography where each handoff carries the explicit context payload, not implicit assumptions about prior state"
+  - "Authoring skills that compose against the LLM-as-CPU model — each skill knows what context it needs and what context it produces"
+anti_patterns:
+  - "Conversational interfaces where the user does not care about the underlying token + context discipline; over-applying Karpathy's framing creates needless friction"
+  - "Pure deterministic pipelines without LLM components — the CPU/RAM framing has no purchase when there is no model in the loop"
+  - "Tiny one-shot prompts where the substrate overhead exceeds the prompt complexity"
+sources:
+  - type: blog_post
+    title: "Software 2.0"
+    authors: ["Andrej Karpathy"]
+    year: 2017
+    url: "https://karpathy.medium.com/software-2-0-a64152b37c35"
+    methodology_covered:
+      - "Software 2.0 — Programs whose logic is learned weights instead of authored statements"
+      - "Source code becomes training data plus architecture; compilation becomes training; debugging becomes dataset inspection plus eval"
+  - type: talk
+    title: "State of GPT (Microsoft Build 2023)"
+    authors: ["Andrej Karpathy"]
+    year: 2023
+    url: "https://www.youtube.com/watch?v=bZQun8Y4L2A"
+    methodology_covered:
+      - "LLM-as-OS framing — model weights are the CPU, context window is the RAM"
+      - "Stateless invocation thinking — every model call starts cold"
+  - type: talk
+    title: "Sequoia AI Ascent 2026 — Software 3.0"
+    authors: ["Andrej Karpathy"]
+    year: 2026
+    url: "https://karpathy.bearblog.dev/sequoia-ascent-2026/"
+    methodology_covered:
+      - "Context window equals RAM, model weights equal CPU, prompting equals programming"
+      - "Context engineering as the new operating-system discipline for LLM-based systems"
+  - type: paper
+    title: "CS231n — Convolutional Neural Networks for Visual Recognition (Stanford)"
+    authors: ["Andrej Karpathy"]
+    year: 2015
+    url: "http://cs231n.stanford.edu/"
+    methodology_covered:
+      - "Field-defining ML pedagogy; the bassclef introduction to neural network internals"
+  - type: blog_post
+    title: "Yes you should understand backprop"
+    authors: ["Andrej Karpathy"]
+    year: 2016
+    url: "https://karpathy.medium.com/yes-you-should-understand-backprop-e2f06eab496b"
+    methodology_covered:
+      - "Foundational essay on training discipline — understand the gradient flow or debugging is guesswork"
+  - type: blog_post
+    title: "A Recipe for Training Neural Networks"
+    authors: ["Andrej Karpathy"]
+    year: 2019
+    url: "http://karpathy.github.io/2019/04/25/recipe/"
+    methodology_covered:
+      - "Operational discipline for ML engineering — systematic process for training neural networks"
+  - type: video
+    title: "Let's build the GPT Tokenizer"
+    authors: ["Andrej Karpathy"]
+    year: 2024
+    url: "https://www.youtube.com/watch?v=zduSFxRajkE"
+    methodology_covered:
+      - "Token economy — tokens are the atomic unit of cost and quality in LLM systems"
+      - "Walking through tokenization mechanics, the foundation of the token-economy framing"
+  - type: blog_post
+    title: "Andrej Karpathy on X (primary methodology venue)"
+    authors: ["Andrej Karpathy"]
+    year: 2025
+    url: "https://x.com/karpathy"
+    methodology_covered:
+      - "Context engineering as a discipline distinct from prompt engineering (coined mid-2025)"
+      - "Stateless invocation thinking — every call starts cold; state must be threaded explicitly"
+verification_status: verified
+description: "\"The LLM is the CPU. The context window is the RAM. Programs are prompts. The job is filling the working memory with exactly the right instructions, data, and examples so the CPU…"
+---
+
+# Andrej Karpathy
+
+## Signature
+
+*"The LLM is the CPU. The context window is the RAM. Programs are prompts. The job is filling the working memory with exactly the right instructions, data, and examples so the CPU can compute the right answer in one pass."*
+
+Stanford PhD; OpenAI co-founder; former Tesla AI Director; CS231n author; widely viewed as the field's most influential teacher. The bassclef voice on **LLM-as-computer** thinking: stateless model + finite context window + tokens-as-instructions. Karpathy named context engineering as a discipline distinct from prompt engineering — and provided the mental model the entire field now uses.
+
+## Core methods
+
+- **LLM-as-CPU, context window-as-RAM** — The model is a stateless computation engine that runs once per invocation. The context window is finite working memory the operator fills before the model fires. Reframes "prompt engineering" as "context engineering": the question is not how to phrase one prompt but how to allocate the context budget across instruction + examples + data + output across an entire system.
+- **Software 2.0** — Programs whose logic is learned weights instead of authored statements. Source code becomes training data + architecture; compilation becomes training; debugging becomes dataset inspection + eval. When bassclef substrate composes against an LLM, the deployed program is partly the model weights (Software 2.0) and partly the substrate's skills + rules + hooks (Software 1.0). Both layers ship; both layers need discipline.
+- **Stateless invocation thinking** — Every model call starts cold. State must be threaded into the context window or recovered from an external store before each call. There is no "the model remembers." Memory + identity + history are substrate concerns, not model capabilities. Designing a multi-agent or multi-turn system without this discipline produces silent state drift.
+- **Token economy** — Tokens are the atomic unit. Cost and quality both vary by token count and token content. Designing for the token budget is a first-class engineering constraint, not an optimization. Skills that allocate their context budget poorly waste cost AND lose quality.
+
+## When to channel this luminary
+
+Channel Karpathy when designing or critiquing the substrate itself — skills, rules, hooks, agent handoffs, prompts. The signal is: substrate decisions hinge on assumptions about what the model "knows" or "remembers" that do not match the stateless-CPU reality.
+
+Channel Karpathy when authoring a new skill or rule. Ask: what context does this skill need? What does it produce? Where does that context come from on each invocation? What does the substrate persist versus re-derive? Without these answers the skill is an ad-hoc text edit, not a programmable substrate component.
+
+INSTEAD of channeling Karpathy for product UX or feature design: Karpathy operates at the LLM-substrate altitude, not the user-facing surface. For UX, route to Cooper + Norman. For positioning, route to Christensen + Dunford. For substrate, route to Karpathy.
+
+## Stack translation
+
+In bassclef's substrate:
+
+- **Skill bodies are program statements for the LLM-CPU** — Each skill's procedure tells the model what to do; each skill's "Sources read" block tells the model what to load. Compositional skills allocate context across sub-skills; the operator-facing prose discipline is itself a context-budget rule.
+- **Rules are background context the substrate guarantees is always present** — Every rule loaded via `additionalDirectories` is unconditional context the model can rely on. Rule clarity (per `.claude/rules/operator-facing-prose.md`) is therefore a context-economy constraint, not a stylistic preference.
+- **Hooks fire before model invocation to populate the working memory correctly** — Session-start hooks load chronicle + whereami + iteration-bet so the model starts the session with state already threaded. Pre-tool-use hooks add gates that fire on the model's behalf. Stop hooks ensure state persists for the next invocation.
+- **Agents are role-specific context shapers** — Each agent definition (`.claude/agents/`) imposes a role-specific frame on the next model invocation. Multi-agent dispatch is multi-context handoff; the iteration-bet-brief-completeness rule exists because a Builder spawned from an Orchestrator starts with no context except what the brief carries.
+- **State spine + chronicles are the "external memory" Karpathy's stateless framing requires** — The substrate keeps state in `state/markers/` + `state/luminary-implementations/` + chronicle/ + docs/whereami.md because the model cannot. Every read from those locations is a context-load step against the stateless-CPU.
+
+## Anti-patterns it prevents
+
+- **Prompt-engineering as text editing** — Treating a skill body as natural-language prose to be polished rather than as a program for a stateless CPU. INSTEAD: ask what the skill loads + what it produces + how its context budget is allocated.
+- **"The model remembers"** — Assuming the next invocation has access to the last one's context. Multi-agent dispatch dies here: an agent spawned via `Agent` tool starts cold. The iteration-bet-brief-completeness rule is the substrate's defense.
+- **Context budget overflow** — Skills + rules + agents all loading large bodies of text without an explicit budget. Context window fills; signal-to-noise drops; model quality collapses. Karpathy's framing forces an explicit budget per substrate component.
+- **Context budget starvation** — The opposite failure: skill bodies too thin to give the model enough discipline. Result is hallucination + inconsistent output. The bar is sufficient context for one-pass correctness, not minimal context.
+- **Implicit state assumptions** — Designing substrate that depends on state the model + harness do not actually persist. The state spine + accessor-library-discipline rule + state-schema-validation rule are all answers to this anti-pattern.
+
+## Worked example
+
+For bassclef's own substrate, applied to a Sunday three-agent dispatch:
+
+**The naive design (without Karpathy framing)**: dispatch Agent A + Agent B + Agent C in parallel; trust each agent to know what to do based on the task description.
+
+**Karpathy's question**: what context does each agent have at invocation? Answer: nothing except the prompt the dispatcher sends. The base bassclef rules load via `additionalDirectories` — that is background context — but everything specific to the task must be threaded in the prompt.
+
+**Substrate responses**:
+
+1. The `iteration-bet-brief-completeness` rule requires every artifact the bet cites to land in the agent prompt verbatim. Without it, the agent starts cold with no context except a short task description, and quality collapses.
+2. The `artifact-ingestion` rule requires the agent to Read every named source before producing output. Reading IS the act of loading context into the working memory.
+3. The `state-spine` substrate persists what each session needs to load on start. Chronicle + whereami + iteration-bet are the substrate's external memory; the model loads them on each invocation because it cannot otherwise remember.
+4. The `auto-save` hook commits state to git before the model's context is lost between sessions. The state-spine entries land via accessors that validate the data — context that is loaded next session is context the substrate guaranteed.
+
+The whole bassclef substrate is Karpathy's mental model expressed as a working system. Adopters who use bassclef without the Karpathy framing build skills + rules + hooks that fight each other because they treat the LLM as persistent. Adopters who internalize Karpathy author substrate that composes cleanly.
+
+## Sources
+
+- *Andrej Karpathy on X* — `https://x.com/karpathy` — primary venue for methodology evolution; threads on LLM internals + context engineering + multi-agent systems are the field's bassclef reading
+- *State of GPT (Microsoft Build 2023)* — Karpathy talk introducing LLM-as-OS framing; `https://www.youtube.com/watch?v=bZQun8Y4L2A` (Microsoft Build official channel)
+- *Software 2.0* (2017 blog post) — `https://karpathy.medium.com/software-2-0-a64152b37c35` — the original essay on neural networks as programs
+- *CS231n: Convolutional Neural Networks for Visual Recognition* — Stanford lecture series authored by Karpathy; `http://cs231n.stanford.edu/` — the field's most-watched ML course
+- *Yes you should understand backprop* (2016) — `https://karpathy.medium.com/yes-you-should-understand-backprop-e2f06eab496b` — foundational essay on training discipline
+- *A Recipe for Training Neural Networks* (2019) — `http://karpathy.github.io/2019/04/25/recipe/` — operational discipline for ML engineering
+- *Let's build the GPT Tokenizer* — `https://www.youtube.com/watch?v=zduSFxRajkE` — multi-hour video walking through tokenization, the atomic unit of the token-economy framing
+
+## Related luminaries
+
+- **Hunt + Thomas** — DRY + KISS + YAGNI compose with Karpathy's token economy. Both disciplines force explicit budget thinking; both prevent the same class of bloat.
+- **Rich Hickey** — Simple vs Easy applies at the prompt + substrate-design altitude. A complected prompt is one that complects instruction + example + data + output without a budget; Karpathy's framing surfaces the complect, Hickey's framing names it.
+- **Kent Beck** — TDD applied to substrate: every skill needs an example of what it produces (the test); every rule needs a context the model can actually use to verify (the assertion). Beck's discipline composes with Karpathy at the substrate layer.
+- **Robert C. Martin** — SOLID applied to skills. Single-responsibility = each skill loads one kind of context; open/closed = skills compose without rewriting; dependency-inversion = skills depend on substrate primitives (state spine + accessor library), not on raw filesystem reads.
+- **Gang of Four** — Patterns compose at the substrate altitude. Strategy = pick the right skill per intent. Decorator = compose-with adds context without rewriting. Observer = hooks. Adapter = state accessor library.

package/dist/lite/.claude/luminaries/dave-gray.md

@@ -0,0 +1,155 @@
+---
+tier: lite
+name: Dave Gray
+slug: dave-gray
+claimed_by: [designer, shaper, product-manager]
+referenced_by_skills: [empathy-map, interview-me, personas]
+primary_domain: design-research
+depth: full
+solves_problems_greenfield:
+  - "Building for a persona whose emotional and observational context is unclear from the interview notes"
+  - "Product team is imagining user needs instead of citing what interviewees actually said or did"
+  - "Discovery phase needs a bridge from raw interview transcripts to synthesized JTBDs"
+  - "New adopter onboarding — an operator needs to shape a persona for their own product without a research team"
+solves_problems_brownfield:
+  - "Existing persona docs are stale, inferred without data, or copied from a competitor deck"
+  - "Team argues about what users want without evidence — the argument itself is the signal"
+  - "Design decisions cite we know our users but the notes to prove it are scattered or missing"
+  - "Adopter persona docs need refresh with real conversation data after 12+ months of drift"
+anti_patterns:
+  - "Inventing quotes in the Say band without a transcript reference"
+  - "Skipping the empathy map because I know the user"
+  - "Empathy-mapping personas the researcher has not interviewed"
+  - "Filling only Think and Feel without evidence in See/Say/Do/Hear"
+sources:
+  - type: book
+    title: "Gamestorming: A Playbook for Innovators, Rulebreakers, and Changemakers"
+    authors: ["Dave Gray", "Sunni Brown", "James Macanufo"]
+    year: 2010
+    publisher: "O'Reilly Media"
+    isbn: "9780596804176"
+    url: "https://www.oreilly.com/library/view/gamestorming/9781449391386/"
+    methodology_covered:
+      - "Original Empathy Map (Says / Thinks / Does / Feels + Pains + Gains)"
+      - "80+ workshop games for design thinking, product discovery, and team facilitation"
+  - type: article
+    title: "Updated Empathy Map Canvas"
+    authors: ["Dave Gray"]
+    year: 2017
+    url: "https://medium.com/@davegray/updated-empathy-map-canvas-46df22df3c8a"
+    methodology_covered:
+      - "7-section canvas — Goal, See, Say, Do, Hear (clockwise sensor bands), Think and Feel (central inference), Pains, Gains"
+      - "Clockwise fill order; sensor bands populated from observation before inference bands"
+  - type: article
+    title: "Empathy Mapping: The First Step in Design Thinking"
+    authors: ["Sarah Gibbons"]
+    year: 2018
+    url: "https://www.nngroup.com/articles/empathy-mapping/"
+    venue: "Nielsen Norman Group"
+    methodology_covered:
+      - "Empathy map as first step in design-thinking process"
+      - "Sparse maps as a research-gap signal — the empty band is the finding"
+      - "One-user vs aggregate empathy mapping trade-offs"
+  - type: book
+    title: "Value Proposition Design"
+    authors: ["Alex Osterwalder", "Yves Pigneur", "Gregory Bernarda", "Alan Smith"]
+    year: 2014
+    publisher: "Wiley"
+    isbn: "9781118968055"
+    url: "https://www.strategyzer.com/library/value-proposition-design"
+    methodology_covered:
+      - "Value Proposition Canvas incorporates the empathy map as the customer-profile companion"
+      - "Jobs / Pains / Gains framing that maps directly to the empathy map's Pains and Gains bands"
+  - type: website
+    title: "XPLANE"
+    url: "https://xplane.com"
+    methodology_covered:
+      - "Gray's consultancy — the visual-thinking practice from which the empathy map emerged in the 2000s"
+verification_status: verified
+verification_note: "Both operator-provided URLs fetched successfully. Gamestorming ISBN and O'Reilly URL verified against the publisher page. XPLANE founding year (1993) is web-knowledge and should be treated as approximate until verified against the company's official history."
+description: "\"The whole idea was to imagine what it's like to be inside someone else's head."
+---
+
+# Dave Gray
+
+## Signature
+
+*"The whole idea was to imagine what it's like to be inside someone else's head. That was and is the primary power of the exercise."* — Gray, Updated Empathy Map Canvas, 2017 [ref:2]
+
+Founder of **XPLANE** — a visual-thinking consultancy founded in 1993 that shaped how large enterprises use pictures and canvases for strategy work. Co-author of **Gamestorming: A Playbook for Innovators, Rulebreakers, and Changemakers** (O'Reilly, 2010) [ref:1] with Sunni Brown and James Macanufo. Creator of the **Empathy Map** — one of the most-adopted user-research canvases in modern design practice. Osterwalder incorporated the empathy map into the Value Proposition Canvas suite in *Value Proposition Design* (2014) [ref:4].
+
+## Core methods
+
+- **Original Empathy Map (2010)** — a persona-centered canvas with four quadrants around a central persona: **Says** (verbatim interview quotes), **Thinks** (internal monologue the user may not voice), **Does** (observable actions), **Feels** (emotional states with context). Two bands underneath: **Pains** (frustrations, obstacles) and **Gains** (wants, measures of success). Fill from real interview data [ref:1].
+- **Updated Empathy Map Canvas (2017)** — 7 sections in a prescribed clockwise sequence. Start with the **Goal** box: define WHO the map is about and what specific goal or observable behavior the map is anchored to. Then fill the sensor quadrants clockwise: **See**, **Say**, **Do**, **Hear**. Then infer the central **Think and Feel** section from what the sensor bands revealed. Close with **Pains** and **Gains** [ref:2].
+- **Sensor vs cognitive/affective split** — See/Say/Do/Hear are observable in the field. Think and Feel is inferred from the sensor bands. The discipline: skip the cognitive band until the sensor bands carry real evidence. INSTEAD of writing "Thinks: worried about deadlines" from imagination: cite a transcript line first ("Says: 'we ship Friday'") and then infer ("Thinks: worried about deadlines because deadlines came up in every answer").
+- **Anchor to a Goal** — the 2017 update added the Goal box specifically because empty-Goal maps drifted into generic persona sketches. A specific goal (e.g., "book their first trip on our platform") keeps the map research-anchored. INSTEAD of starting with "the user" as a fuzzy noun: name the specific goal the user is pursuing, then map the persona in relation to that goal [ref:2].
+
+## When to channel this luminary
+
+Fire during design research synthesis, product discovery, and adopter-persona work. Bassclef applications:
+
+- `/empathy-map` skill (ship in bet 2026-07-07a) walks the 2017 7-section canvas
+- `/interview-me` skill uses the empathy map as Step 3 (pains/gains/needs from an adopter interview)
+- Adopter-persona docs — bassclef's own operator persona files could use the Gray canvas as the underlying research shape
+- Product-canvas work when a bassclef adopter is shaping their first product and needs a research-anchored persona
+
+INSTEAD of channeling Gray when there is no interview data: run interviews first. An empathy map filled from imagination is a persona sketch, not a research artifact. Sarah Gibbons at NN/g makes this point directly [ref:3].
+
+## Stack translation
+
+Interview transcripts to filled empathy map:
+
+- Verbatim quotes → **Say** (with a transcript timestamp reference)
+- Body-language and observation notes → **Do**
+- Reported hearing ("my boss keeps telling me…") → **Hear**
+- Environmental context ("she works at a shared desk with three monitors") → **See**
+- After the four sensor bands carry real evidence, the researcher infers **Think and Feel** — each inference cites the transcript line it rests on
+- Frustrations and blockers named by the user → **Pains**
+- Desired outcomes and measures of success → **Gains**
+
+The bassclef `/empathy-map` skill will accept a persona description as input, walk the 7 sections in order (Goal first), and produce a structured markdown or JSON snippet ready to feed downstream skills like `/interview-me`, `/lean-canvas`, and `/pre-mortem` (persona-affected-by-failure lens).
+
+## Anti-patterns it prevents
+
+- **Fiction in the Say band** — writing quotes without a transcript reference. Gray's canvas is a research artifact. INSTEAD of imagining what the user might say: cite the transcript timestamp or leave the band empty and treat that as the research gap.
+- **"I know the user" skip** — deciding the empathy map is redundant because the tacit knowledge is already in your head. INSTEAD of skipping: write down the tacit knowledge in the sensor bands. If writing it down surfaces a claim you cannot cite, that IS the finding.
+- **Persona-mapping without interviews** — filling all 7 sections for a persona the team has not talked to. The sensor bands do not carry evidence. INSTEAD of inferring from analogies: leave the sensor bands empty and mark them as "research needed"; NN/g's framing is that sparse maps signal more interviews are owed [ref:3].
+- **Inference-only maps** — filling only Think and Feel while leaving the sensor bands empty. The inference bands sit on top of the sensor bands and lose their epistemic anchor without them. INSTEAD of filling inference first: fill sensor bands from observation; then infer Think and Feel with each inference citing the sensor evidence it rests on.
+
+## Worked example (bassclef application)
+
+For a bassclef adopter's first persona ("small-team CTO shipping an internal ops tool"):
+
+1. **Goal box** — "Ship a working ops tool in 6 weeks that the team actually uses."
+2. **See** — "Works in an open plan office; sees other engineers' screens all day; sees Slack messages piling up; sees the ops team using a spreadsheet for the current process."
+3. **Say** — [verbatim quotes from a 45-minute interview, tagged to transcript timestamps]
+4. **Do** — "Opens the sandbox at start of every workday; reviews yesterday's shipping metrics before the standup; deploys 3-5 times per day; writes design docs before every big feature."
+5. **Hear** — "Team asks for X, PM asks for Y, board asks for Z; the three demands often conflict."
+6. **Think and Feel** — inferred: "worries the team will hit rate limits mid-quarter; feels responsible for both technical and product direction; frustrated by tool sprawl."
+7. **Pains** — "Every new tool requires an onboarding session; loses 2 days per new hire; watches other CTOs ship faster with worse code."
+8. **Gains** — "Wants team velocity to compound; wants to spend more time on architecture and less on triage; wants tools that work on day one."
+
+Each cell cites a transcript line or field-notes reference. The output feeds `/interview-me` Step 3 and downstream JTBD synthesis.
+
+## Sources
+
+1. Gray, D., Brown, S., & Macanufo, J. (2010). *Gamestorming: A Playbook for Innovators, Rulebreakers, and Changemakers.* O'Reilly Media. ISBN 9780596804176 [ref:1]
+2. Gray, D. (2017). "Updated Empathy Map Canvas." Medium. https://medium.com/@davegray/updated-empathy-map-canvas-46df22df3c8a [ref:2]
+3. Gibbons, S. (2018). "Empathy Mapping: The First Step in Design Thinking." Nielsen Norman Group. https://www.nngroup.com/articles/empathy-mapping/ [ref:3]
+4. Osterwalder, A., Pigneur, Y., Bernarda, G., & Smith, A. (2014). *Value Proposition Design.* Wiley. ISBN 9781118968055 [ref:4]
+5. XPLANE. https://xplane.com — Gray's consultancy; visual-thinking practice from which the empathy map emerged
+
+## Related luminaries
+
+- **Sunni Brown** — Gamestorming co-author; *The Doodle Revolution* (2014); visual-thinking practitioner and co-creator of the original empathy map
+- **James Macanufo** — Gamestorming co-author
+- **Alex Osterwalder** — *Business Model Generation* (2010) and *Value Proposition Design* (2014); incorporated the empathy map into the Strategyzer canvas suite
+- **Yves Pigneur** — Osterwalder co-author, *Business Model Generation*
+- **Sarah Gibbons / Nielsen Norman Group** — authoritative UX-research treatment of the empathy map's practical use; the "sparse map is a finding" framing
+- **Tony Ulwick** — JTBD (Jobs-to-be-Done) framework; complementary to empathy mapping (Ulwick asks WHAT the user is trying to accomplish; Gray asks WHO the user IS while trying)
+- **Ash Maurya** — lean-canvas author; the empathy map feeds the customer-segment and problem boxes of the lean canvas
+
+## Substrate-as-system anchor (bassclef)
+
+Gray's empathy map anchors bet 2026-07-07a's `/empathy-map` skill (ticket #657) and feeds `/interview-me` (ticket #653) at Step 3. The bassclef application preserves Gray's discipline (sensor-first, inference-after, cite the transcript) but adapts the collection shape from a workshop wall to a conversational skill: Claude prompts each section in Gray's clockwise order; operator answers with what they observed; Claude captures without inventing quotes; the output is a structured empathy map artifact stored under `docs/personas/<slug>-empathy-map.md`. The 2017 update's Goal-first sequence maps directly to bassclef's discipline of anchoring every artifact to a specific outcome before elaboration.