@thebassclef/lite 1.0.3 → 1.1.0

package/dist/lite/.claude/hooks/longrun-prep-render-check.sh

@@ -0,0 +1,236 @@
+#!/usr/bin/env bash
+# tier: lite
+# install-class: dual
+# PostToolUse: Stop
+#
+# /longrun prep render check — closes ticket #1632.
+#
+# Fires four render-shape checks against the latest assistant message
+# when the message carries a /longrun prep proposal:
+#
+#   Symptom 1 — path label repetition. Every axis section repeating
+#     "Path A / Path B / Path C" as row prefixes = pure chart-junk per
+#     Tufte. Threshold: option labels appearing > 3 * option_count
+#     outside table header rows triggers BLOCK.
+#
+#   Symptom 2 — no progressive disclosure. Recommend line declares
+#     Option X but multiple options carry full 6-axis blocks. Per
+#     Norman progressive disclosure + ADR-055 D3 recommended-only
+#     shape. Trigger: 2+ #### Option X sections beneath a
+#     "### Compounding value — recommended only" anchor when a
+#     Recommend line is present.
+#
+#   Symptom 3 — TUI-unsafe table cells. Cells holding apostrophes,
+#     parens, or em-dashes fracture at Claude Code TUI render. Per
+#     .claude/rules/visual-hierarchy.md §12. Trigger: any markdown
+#     table row (starts and ends with |) carries [']()—] inside a cell
+#     (excluding header separator rows).
+#
+#   Symptom 4 — "(Via /SKILL)" placeholder leak. Template placeholder
+#     text should be substituted with the dispatched skill name.
+#     Trigger: literal "(Via /SKILL)" appears in the message.
+#
+# Anchor luminaries:
+#   @luminary don-norman — progressive disclosure, signifier
+#   @luminary edward-tufte — data-ink ratio, chart-junk
+#   @luminary michael-feathers — characterization tests
+#   @luminary kent-beck — Tier 0 strict-TDD
+#
+# Toggle (default advisory; flip strict after calibration cycle):
+#   LONGRUN_PREP_RENDER_CHECK_TOGGLE=strict   → exit 2 on any finding
+#   LONGRUN_PREP_RENDER_CHECK_TOGGLE=advisory → exit 0, findings to stderr (default)
+#   LONGRUN_PREP_RENDER_CHECK_TOGGLE=silent   → exit 0, no output
+#
+# Override per-call:
+#   SKIP_LONGRUN_PREP_RENDER_CHECK=1
+
+set -uo pipefail
+
+# Override — skip and log
+if [ "${SKIP_LONGRUN_PREP_RENDER_CHECK:-0}" = "1" ]; then
+  echo "[longrun-prep-render-check: SKIPPED via SKIP_LONGRUN_PREP_RENDER_CHECK=1]" >&2
+  exit 0
+fi
+
+TOGGLE="${LONGRUN_PREP_RENDER_CHECK_TOGGLE:-advisory}"
+
+# Silent mode — exit clean
+if [ "$TOGGLE" = "silent" ]; then
+  exit 0
+fi
+
+# Fixture-mode override (tests) — checked FIRST so fixture content is
+# the source of truth when the env var is set. Skips the transcript
+# extraction entirely.
+if [ -n "${LONGRUN_PREP_RENDER_FIXTURE:-}" ] && [ -f "${LONGRUN_PREP_RENDER_FIXTURE}" ]; then
+  MESSAGE_TEXT="$(cat "${LONGRUN_PREP_RENDER_FIXTURE}")"
+else
+  # Normal runtime path — read stdin JSON + extract latest assistant message
+  STDIN_JSON="$(cat 2>/dev/null || echo '{}')"
+  TRANSCRIPT_PATH="$(echo "$STDIN_JSON" | jq -r '.transcript_path // empty' 2>/dev/null || echo "")"
+
+  if [ -z "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIPT_PATH" ]; then
+    exit 0
+  fi
+
+  MESSAGE_TEXT="$(jq -r '
+    select(.type == "assistant")
+    | .message.content[]?
+    | select(.type == "text")
+    | .text
+  ' "$TRANSCRIPT_PATH" 2>/dev/null | tail -c 32000)"
+fi
+
+if [ -z "$MESSAGE_TEXT" ]; then
+  exit 0
+fi
+
+# Only fire on messages that look like /longrun prep proposals.
+# Anchor patterns per SKILL body Step 1.5-1.7:
+#   - "### Compare options" — the scan-table anchor
+#   - "### Compounding value" — the axis block anchor
+#   - "**Recommend:**" — the recommendation opener
+# If none of these appear, this is not a prep proposal; skip.
+if ! echo "$MESSAGE_TEXT" | grep -qE '(### Compare options|### Compounding value|\*\*Recommend:\*\*)'; then
+  exit 0
+fi
+
+FINDINGS=""
+FINDING_COUNT=0
+
+# =========================================================================
+# Symptom 1 — Path label repetition (Tufte chart-junk)
+# =========================================================================
+#
+# Count occurrences of "Option [a-z]" or "Path [A-Z]" or "Shape [a-c]" in
+# non-comment / non-fenced-code lines. Deduct one occurrence per option
+# for the header row + one for the Recommend line + one for the card
+# section header. If remaining count > 0, we have per-option axis
+# repetition — the chart-junk pattern.
+#
+# Threshold: per-option axis repetition means 6+ extra label rows per
+# option. If the total residual count is > 3, the anti-pattern is present.
+LABEL_TOTAL=$(echo "$MESSAGE_TEXT" | \
+  grep -vE '^[[:space:]]*```' | \
+  grep -oE '\b(Option [a-z]|Path [A-Z]|Shape [a-c])\b' | wc -l | tr -d ' ')
+OPTION_COUNT=$(echo "$MESSAGE_TEXT" | \
+  grep -vE '^[[:space:]]*```' | \
+  grep -oE '\b(Option [a-z]|Path [A-Z]|Shape [a-c])\b' | sort -u | wc -l | tr -d ' ')
+
+# Baseline: header row + card section + recommend line + one summary sentence.
+# Estimate ~4 legitimate uses per option label.
+BASELINE=$((OPTION_COUNT * 4))
+
+if [ "$LABEL_TOTAL" -gt "$BASELINE" ] && [ "$OPTION_COUNT" -ge 2 ]; then
+  EXCESS=$((LABEL_TOTAL - BASELINE))
+  FINDINGS="${FINDINGS}
+Symptom 1 — path label repetition (Tufte chart-junk):
+  ${LABEL_TOTAL} option-label mentions across ${OPTION_COUNT} options
+  (baseline ~${BASELINE}; excess ~${EXCESS})
+  Cure — collapse per-axis 'Option A / B / C' rows into ONE header naming
+  options once, then rows carry values without re-labeling."
+  FINDING_COUNT=$((FINDING_COUNT + 1))
+fi
+
+# =========================================================================
+# Symptom 2 — no progressive disclosure (Norman)
+# =========================================================================
+#
+# Fires when Recommend line declares Option X AND non-recommended options
+# ALSO carry full 6-axis "#### Option Y" cards beneath the
+# "### Compounding value — recommended only" anchor. Per bassclef-upstream
+# #1376 + ADR-055 D3, only the recommended option gets a full card.
+RECOMMENDED=$(echo "$MESSAGE_TEXT" | \
+  grep -oE '\*\*Recommend[^*]*\*\*[[:space:]]*(Option [a-z]|Path [A-Z]|Shape [a-c])' | \
+  head -1 | grep -oE '(Option [a-z]|Path [A-Z]|Shape [a-c])' | head -1)
+
+if [ -n "$RECOMMENDED" ]; then
+  # Count #### Option X headers under the recommended-only anchor
+  CARD_HEADERS_UNDER_ANCHOR=$(echo "$MESSAGE_TEXT" | awk '
+    /^### Compounding value/ { in_anchor=1; next }
+    /^### / && in_anchor { in_anchor=0 }
+    in_anchor && /^#### (Option [a-z]|Path [A-Z]|Shape [a-c])/ { print }
+  ' | wc -l | tr -d ' ')
+
+  if [ "$CARD_HEADERS_UNDER_ANCHOR" -ge 2 ]; then
+    FINDINGS="${FINDINGS}
+Symptom 2 — no progressive disclosure (Norman):
+  Recommend declared '${RECOMMENDED}' but ${CARD_HEADERS_UNDER_ANCHOR}
+  #### Option cards appear under '### Compounding value — recommended only'
+  Cure — render ONE card for the recommended option only. Non-recommended
+  options carry axes as one-liner cells in the scan-table row above.
+  See .claude/rules/compounding-sequence-fresh-analysis.md postcondition."
+    FINDING_COUNT=$((FINDING_COUNT + 1))
+  fi
+fi
+
+# =========================================================================
+# Symptom 3 — TUI-unsafe table cells (visual-hierarchy §12)
+# =========================================================================
+#
+# Detect markdown table rows (start and end with |, not separator rows)
+# that carry apostrophes, parens, or em-dashes inside cell text.
+# Per .claude/rules/visual-hierarchy.md §12 — card format is the cure.
+UNSAFE_CELL_LINES=$(echo "$MESSAGE_TEXT" | \
+  grep -E '^\|.*\|[[:space:]]*$' | \
+  grep -vE '^\|[[:space:]:-]+\|' | \
+  grep -E "['()—]" | head -3)
+
+if [ -n "$UNSAFE_CELL_LINES" ]; then
+  UNSAFE_COUNT=$(echo "$UNSAFE_CELL_LINES" | wc -l | tr -d ' ')
+  FINDINGS="${FINDINGS}
+Symptom 3 — TUI-unsafe table cells (visual-hierarchy §12):
+  ${UNSAFE_COUNT} table row(s) carry apostrophes / parens / em-dashes
+  in cell text. First offending row:
+    $(echo "$UNSAFE_CELL_LINES" | head -1 | cut -c1-120)
+  Cure — move affected content to card format (bullets under a heading)
+  or replace ' with U+2019, replace () with plain prose, replace — with
+  HTML entity or backticks."
+  FINDING_COUNT=$((FINDING_COUNT + 1))
+fi
+
+# =========================================================================
+# Symptom 4 — "(Via /SKILL)" placeholder leak
+# =========================================================================
+#
+# Detect literal "(Via /SKILL)" or "(via /SKILL)" or "(/SKILL)" in the
+# message. These are template placeholders that should have been
+# substituted with the actual dispatched skill name.
+LEAK_COUNT=$(echo "$MESSAGE_TEXT" | grep -cE '\((Via|via) /SKILL\)|\(/SKILL\)' 2>/dev/null | tr -d '[:space:]' || echo 0)
+LEAK_COUNT="${LEAK_COUNT:-0}"
+
+if [ "$LEAK_COUNT" -gt 0 ]; then
+  FINDINGS="${FINDINGS}
+Symptom 4 — '(Via /SKILL)' placeholder leak:
+  ${LEAK_COUNT} literal placeholder(s) in message. Should be substituted
+  with the dispatched skill name (e.g., 'via /state-a-problem brief').
+  Cure — replace each '(Via /SKILL)' with 'via /<actual-skill>' or drop
+  the citation if no skill fired."
+  FINDING_COUNT=$((FINDING_COUNT + 1))
+fi
+
+# =========================================================================
+# Emit + exit per toggle
+# =========================================================================
+
+if [ "$FINDING_COUNT" -eq 0 ]; then
+  exit 0
+fi
+
+case "$TOGGLE" in
+  strict)
+    echo "🛑 LONGRUN-PREP-RENDER — BLOCKED (${FINDING_COUNT} finding(s); ticket #1632)" >&2
+    echo "$FINDINGS" >&2
+    echo "" >&2
+    echo "Override: SKIP_LONGRUN_PREP_RENDER_CHECK=1" >&2
+    exit 2
+    ;;
+  *)
+    # Default: advisory
+    echo "⚠ LONGRUN-PREP-RENDER — ADVISORY (${FINDING_COUNT} finding(s); ticket #1632)" >&2
+    echo "$FINDINGS" >&2
+    echo "" >&2
+    echo "Flip to strict via LONGRUN_PREP_RENDER_CHECK_TOGGLE=strict" >&2
+    exit 0
+    ;;
+esac

package/dist/lite/.claude/hooks/persona-name-scrub-check.sh

@@ -0,0 +1,105 @@
+#!/bin/bash
+# tier: lite
+# install-class: dual
+# persona-name-scrub-check — PreToolUse hook that scans SKILL descriptions,
+# SKILL bodies, rule bodies, luminary bodies, and adopter-facing docs
+# (docs/**/*.md, docs-site/content/**/*.{md,mdx}) for bassclef persona
+# proper nouns (Sam, Louis, Jamie, Morgan).
+#
+# V1 (bassclef-web#327): description-only scope.
+# V2 (bassclef-web#339): body scope + adopter-facing docs paths.
+#
+# Per .claude/rules/persona-name-leak-scrub.md.
+# V1+V2 ADVISORY per ADR-031 grace window. Exit 0 with stderr finding.
+# V3 BLOCK deferred pending calibration cycle.
+#
+# Exit codes:
+#   0 — allow (non-matching path, non-Edit/Write, clean content, or override)
+#
+# Override: SKIP_PERSONA_NAME_SCRUB=1
+
+set +e
+
+INPUT=$(cat 2>/dev/null)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""' 2>/dev/null)
+
+# Only fire on Edit or Write or MultiEdit
+case "$TOOL_NAME" in
+  Edit|Write|MultiEdit) ;;
+  *) exit 0 ;;
+esac
+
+# Override path
+if [ "${SKIP_PERSONA_NAME_SCRUB:-}" = "1" ]; then
+  exit 0
+fi
+
+# Path scope decision — V2 broadened per bassclef-web#339
+# Order matters: skip docs/personas/*.md BEFORE the docs/*.md general match
+case "$FILE_PATH" in
+  */docs/personas/*.md)
+    exit 0 ;;
+  */.claude/skills/*/SKILL.md) ;;
+  */.claude/rules/*.md) ;;
+  */.claude/luminaries/*.md) ;;
+  */docs-site/content/*.md|*/docs-site/content/*.mdx) ;;
+  */docs/*.md) ;;
+  *) exit 0 ;;
+esac
+
+# Extract content — Write → content; Edit → new_string; MultiEdit → concat edits[].new_string
+CONTENT=""
+if [ "$TOOL_NAME" = "Write" ]; then
+  CONTENT=$(echo "$INPUT" | jq -r '.tool_input.content // ""' 2>/dev/null)
+elif [ "$TOOL_NAME" = "MultiEdit" ]; then
+  CONTENT=$(echo "$INPUT" | jq -r '[.tool_input.edits[]? | .new_string] | join("\n")' 2>/dev/null)
+else
+  CONTENT=$(echo "$INPUT" | jq -r '.tool_input.new_string // ""' 2>/dev/null)
+fi
+
+[ -z "$CONTENT" ] && exit 0
+
+# Strip false-positive sources BEFORE regex scan (R4 + R12 mitigations):
+#   1. Fenced code blocks (``` ... ```)
+#   2. Inline backtick spans (`...`)
+# awk + sed pipeline. Order: fenced first (multi-line), then inline (single-line).
+STRIPPED=$(echo "$CONTENT" | awk '
+  BEGIN { in_block = 0 }
+  /^```/ { in_block = !in_block; next }
+  { if (!in_block) print }
+' | sed 's/`[^`]*`//g')
+
+# Word-boundary case-sensitive regex for persona proper nouns.
+# grep -E for extended regex, -o extracts matches for the ADVISORY report.
+MATCHES=$(echo "$STRIPPED" | grep -oE '\b(Sam|Louis|Jamie|Morgan)\b' 2>/dev/null | sort -u | tr '\n' ' ')
+
+if [ -n "$MATCHES" ]; then
+  # Determine scope label for the ADVISORY (description vs body vs docs)
+  SCOPE_LABEL="body"
+  if echo "$STRIPPED" | grep -qE '^description:.*\b(Sam|Louis|Jamie|Morgan)\b'; then
+    SCOPE_LABEL="description"
+  fi
+  case "$FILE_PATH" in
+    */docs/*|*/docs-site/*) SCOPE_LABEL="adopter-facing content" ;;
+  esac
+
+  cat >&2 <<EOF
+⚠ PERSONA-NAME-SCRUB — ADVISORY (V2)
+
+  File:  $FILE_PATH
+  Scope: $SCOPE_LABEL
+  Match: $MATCHES
+
+  Adopters read SKILL bodies + rules + luminaries + docs. They have
+  no context on bassclef persona names. Substitute role words —
+  writer, picker, reviewer, operator, adopter.
+
+  Or backtick the name if it names a variable / quoted external ref.
+
+  Per .claude/rules/persona-name-leak-scrub.md
+  Override (logged): SKIP_PERSONA_NAME_SCRUB=1
+EOF
+fi
+
+exit 0

package/dist/lite/.claude/hooks/skill-step-list-check.sh

@@ -0,0 +1,171 @@
+#!/bin/bash
+# tier: lite
+# install-class: dual
+# Skill-step-list check — Stop hook that scans the transcript for a Skill tool
+# dispatch followed by an assistant response without a step-list block.
+#
+# Per sunj-labs/bassclef-upstream#1119: closes the SKILL-step-skip class caught
+# in session 2026-08-05a. Rule at .claude/rules/skill-procedure-step-list.md.
+# Ships as pair per bootstrap-pair-discipline.md.
+#
+# Sibling pattern: .claude/hooks/turn-prose-kiss-check.sh (Stop hook + transcript scan).
+#
+# Input (stdin): JSON with transcript_path + session_id
+#   {"transcript_path": "/path/to/transcript.jsonl", "session_id": "..."}
+#
+# Toggle (env or .claude/bassclef-configs.jsonc):
+#   SKILL_STEP_LIST_TOGGLE=true    — advisory (exit 0, findings to stderr) [DEFAULT]
+#   SKILL_STEP_LIST_TOGGLE=strict  — strict (exit 2, blocks stop, forces rewrite)
+#   SKILL_STEP_LIST_TOGGLE=false   — silent (exit 0, no scan)
+#
+# Override per-call:
+#   SKIP_SKILL_STEP_LIST=1         — skip scan, exit 0
+#
+# Exit codes:
+#   0 — pass (no findings, advisory mode, toggle off, override set, or no Skill dispatched)
+#   2 — block stop (strict mode + Skill dispatched + no step-list in response)
+#
+# Reads:
+#   - $TRANSCRIPT_PATH (JSONL, one event per line)
+#   - .claude/bassclef-configs.jsonc (toggle when env not set)
+
+set +e
+
+# === Override path ===
+if [ "${SKIP_SKILL_STEP_LIST:-0}" = "1" ]; then
+  exit 0
+fi
+
+# === Source install-class resolver ===
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Hook liveness heartbeat (silent-fail)
+{
+  for _hb_c in "${SCRIPT_DIR}/../../lib/hook-heartbeat.sh" "${HOME:-/}/lib/hook-heartbeat.sh"; do
+    [ -f "$_hb_c" ] && source "$_hb_c" && heartbeat_mark "skill-step-list-check" && break
+  done
+  unset _hb_c
+} 2>/dev/null || true
+
+for _candidate in \
+  "${SCRIPT_DIR}/../../lib/hook-inject.sh" \
+  "${HOME_OVERRIDE:-${HOME:-/}}/lib/hook-inject.sh"; do
+  if [ -f "$_candidate" ]; then
+    # shellcheck disable=SC1090
+    source "$_candidate"
+    break
+  fi
+done
+unset _candidate
+
+# === Parse stdin JSON ===
+STDIN_JSON=$(cat 2>/dev/null || echo '{}')
+TRANSCRIPT_PATH=$(echo "$STDIN_JSON" | jq -r '.transcript_path // ""' 2>/dev/null)
+
+# Graceful skip if no transcript path
+if [ -z "$TRANSCRIPT_PATH" ]; then
+  exit 0
+fi
+
+# Graceful skip if transcript file missing
+if [ ! -f "$TRANSCRIPT_PATH" ]; then
+  exit 0
+fi
+
+# === Resolve config file ===
+if declare -f resolve_config_path >/dev/null 2>&1; then
+  CONFIG_FILE=$(resolve_config_path 2>/dev/null) || CONFIG_FILE=""
+else
+  CONFIG_FILE="${SCRIPT_DIR}/../bassclef-configs.jsonc"
+fi
+
+# === Resolve toggle ===
+TOGGLE="${SKILL_STEP_LIST_TOGGLE:-}"
+if [ -z "$TOGGLE" ]; then
+  if [ -n "$CONFIG_FILE" ] && [ -f "$CONFIG_FILE" ]; then
+    TOGGLE=$(sed 's|//.*||g' "$CONFIG_FILE" 2>/dev/null \
+      | jq -r '.skill_step_list.toggle // "true"' 2>/dev/null)
+  fi
+  TOGGLE="${TOGGLE:-true}"
+fi
+
+case "$TOGGLE" in
+  true|"true") MODE="advisory" ;;
+  strict|"strict") MODE="strict" ;;
+  false|"false") exit 0 ;;
+  *) MODE="advisory" ;;
+esac
+
+# === Scan transcript for a Skill tool_use ===
+# We scan the last 200 lines to keep the hook fast.
+LAST_LINES=$(tail -200 "$TRANSCRIPT_PATH" 2>/dev/null)
+
+# Find lines with Skill tool_use
+SKILL_LINE_NUM=$(echo "$LAST_LINES" | grep -n '"type":"tool_use"' 2>/dev/null | grep '"name":"Skill"' | tail -1 | cut -d: -f1)
+
+if [ -z "$SKILL_LINE_NUM" ]; then
+  # No Skill dispatched in recent transcript — silent pass
+  exit 0
+fi
+
+# === Find the assistant text_content event AFTER the Skill line ===
+# The response we care about is the one after the Skill tool_result comes back.
+AFTER_SKILL=$(echo "$LAST_LINES" | tail -n +"$((SKILL_LINE_NUM + 1))" 2>/dev/null)
+
+# Get the latest assistant text_content in that portion
+LAST_ASSISTANT_AFTER=$(echo "$AFTER_SKILL" | grep '"type":"assistant"' | tail -1)
+
+if [ -z "$LAST_ASSISTANT_AFTER" ]; then
+  # Skill dispatched but no response yet — silent pass
+  exit 0
+fi
+
+# Extract text content from the assistant message
+MESSAGE_TEXT=$(echo "$LAST_ASSISTANT_AFTER" \
+  | jq -r '.message.content[]? |
+      if .type == "text" then
+        .text
+      else
+        empty
+      end' 2>/dev/null)
+
+if [ -z "$MESSAGE_TEXT" ]; then
+  # Assistant message had no text content (tool_use only) — silent pass
+  exit 0
+fi
+
+# === Check for step-list pattern ===
+# Pattern: two markers must both appear:
+#   1. A "Step N" reference (Step + digit)
+#   2. At least one "[x]" or "[~]" bracket status marker
+HAS_STEP=$(echo "$MESSAGE_TEXT" | grep -cE 'Step[[:space:]]+[0-9]+' 2>/dev/null)
+HAS_MARKER=$(echo "$MESSAGE_TEXT" | grep -cE '\[[x~]\]' 2>/dev/null)
+
+if [ "$HAS_STEP" -gt 0 ] && [ "$HAS_MARKER" -gt 0 ]; then
+  # Step-list present — silent pass
+  exit 0
+fi
+
+# === Missing step-list — emit finding ===
+NOTICE="SKILL step-list check: recent Skill dispatch response lacks a step-list block."
+NOTICE="$NOTICE Per .claude/rules/skill-procedure-step-list.md,"
+NOTICE="$NOTICE write each SKILL procedure step with [x] done+source OR [~] deferred+reason."
+
+# Trace log if trace-helper available
+if [ -f "${SCRIPT_DIR}/../../lib/trace-helper.sh" ]; then
+  source "${SCRIPT_DIR}/../../lib/trace-helper.sh" 2>/dev/null
+  if declare -f trace_record >/dev/null 2>&1; then
+    trace_record "skill-step-list-check" "advisory-fired" "$NOTICE" 2>/dev/null
+  fi
+fi
+
+if [ "$MODE" = "strict" ]; then
+  echo "🛑 BLOCKED: $NOTICE" >&2
+  echo "" >&2
+  echo "To resolve: rewrite the response with a step list at the top." >&2
+  echo "Override: SKIP_SKILL_STEP_LIST=1 <command> (logged)" >&2
+  exit 2
+else
+  echo "⚠ ADVISORY: $NOTICE" >&2
+  exit 0
+fi

package/dist/lite/.claude/luminaries/alan-cooper.md

@@ -0,0 +1,170 @@
+---
+tier: lite
+name: Alan Cooper
+slug: alan-cooper
+claimed_by: [designer]
+referenced_by_skills: [ia-model, jtbd-tasks, task-scenarios]
+primary_domain: ux
+depth: full
+sources:
+  - type: book
+    title: "About Face: The Essentials of Interaction Design (4th edition)"
+    authors: ["Alan Cooper", "Robert Reimann", "David Cronin", "Christopher Noessel"]
+    year: 2014
+    url: "https://www.wiley.com/en-us/About+Face%3A+The+Essentials+of+Interaction+Design%2C+4th+Edition-p-9781118766576"
+    isbn: "9781118766576"
+    methodology_covered:
+      - "Goal-Directed Design — design starts from user goals, not features or tasks"
+      - "Personas as design tools — composite archetypes derived from user research"
+      - "Scenarios — narrative descriptions of personas using the product to achieve goals"
+      - "Three categories of users: novice + intermediate + expert; design for the perpetual intermediate"
+  - type: book
+    title: "The Inmates Are Running the Asylum: Why High-Tech Products Drive Us Crazy and How to Restore the Sanity"
+    authors: ["Alan Cooper"]
+    year: 1999
+    url: "https://www.pearson.com/en-us/subject-catalog/p/inmates-are-running-the-asylum-the-why-high-tech-products-drive-us-crazy-and-how-to-restore-the-sanity/P200000009296"
+    isbn: "9780672326141"
+    methodology_covered:
+      - "Programmer-driven design produces hostile interfaces"
+      - "Interaction designers as a distinct discipline, separate from engineering"
+      - "Persona origin — Cooper's first published articulation of the persona methodology"
+verification_status: verified
+solves_problems_brownfield:
+  - "Existing UI exposes the system's structure when users want their workflow"
+  - "Power users keep retracing the same multi-step path through the current UI"
+  - "Persona research surfaces a goal but the existing UI optimizes for novice exploration"
+  - "App is feature-rich but each user wants only one slice for their job"
+solves_problems_greenfield:
+  - "Designing a workflow-heavy app for returning users with named goals"
+  - "Building a product where personas + scenarios should drive the UI before any screen sketch"
+  - "Planning a tool for power users who need their job-specific slice surfaced from day one"
+  - "Mid-complexity product where personas keep early design decisions grounded in real users"
+anti_patterns:
+  - "Truly simple consumer apps — Cooper overweights workflow modeling"
+  - "First-launch novelty experiences — goal-directed assumes a returning user"
+  - "Pure marketing or storytelling surfaces"
+description: "\"Personas are precision tools — each one a research-grounded behavioral archetype, not a fictional user."
+---
+
+# Alan Cooper
+
+## Signature
+
+*"Personas are precision tools — each one a research-grounded behavioral archetype, not a fictional user. Start with user goals and let personas carry you there."*
+
+"Father of Visual Basic"; founder of Cooper (the consultancy); author of
+**About Face** and **The Inmates Are Running the Asylum**. The bassclef
+voice on **Goal-Directed Design** and the proper use of personas as
+research artifacts.
+
+## Core methods
+
+- **Goal-Directed Design** — Start with user goals (what they want to
+  accomplish, at life/experience/end levels), then derive tasks, then
+  derive interface. Feature-first design inverts this and produces
+  feature-dense, goal-incoherent products.
+- **Personas as behavioral archetypes** — Built from interview pattern
+  analysis, not invented. Each persona represents a distinct goal set +
+  mental model + behavior pattern. A good product serves a primary
+  persona ruthlessly; secondary personas are served if it doesn't
+  compromise the primary.
+- **Three levels of goals** — Life goals (long-term aspirations),
+  experience goals (how the interaction should feel), end goals (what
+  they want to accomplish in this session). Life goals shape brand;
+  experience goals shape interaction; end goals shape task flow.
+- **Scenarios over requirements** — Describe the user in their context
+  pursuing their goal. A list of requirements decomposes; a scenario
+  holds the context that makes requirements make sense.
+- **Dancing bear anti-pattern** — When something is remarkable *that it
+  works at all*, we accept it despite being difficult to use. Enterprise
+  software especially. Cooper's insight: don't accept the dancing bear.
+
+## When to channel this luminary
+
+When the biggest risk is building the wrong thing for the wrong person.
+Cooper dominates when you have a target user population with distinct
+behavior patterns, when goals (not features) should drive the product,
+and when the risk of serving-everyone-badly is real. Think: operator
+tools where the primary user does this job all day, specialist tools
+where casual users will never be the target, B2B products with clear
+user roles.
+
+Do NOT channel Cooper as primary for: consumer products with vague
+personas, rapid prototyping where persona rigor is premature, projects
+where research budget doesn't support proper persona development (use
+lightweight JTBD instead).
+
+## Stack translation
+
+In a Next.js + Prisma operator tool:
+
+- **User goals → top-level nav** — If the primary persona's goal is
+  "move deals through pipeline efficiently," nav centers on deal flow,
+  not on feature taxonomy.
+- **Personas → role-based access + UI variants** — Actual personas
+  often map to auth roles (Operator vs Broker vs Viewer). Each role
+  gets a goal-optimized surface, not a feature-subset of a generic UI.
+- **Scenarios → key path tests** — Each scenario becomes an end-to-end
+  test that walks through the persona's goal. If the scenario breaks,
+  the product breaks for that persona.
+- **Primary persona dominance** — When Primary Persona and Secondary
+  Persona needs conflict, Primary wins. Tailwind variants, conditional
+  rendering, feature flags — all serve this.
+
+## Anti-patterns it prevents
+
+- **Self-referential design** — designing for ourselves because we're
+  easy to imagine. Cooper's rigor demands research-grounded personas.
+- **Generic "the user"** — vague singular user that's really an
+  amalgam of all users. Produces features for all, good-fit for none.
+- **Feature-driven roadmap** — building because the feature was
+  requested, not because it serves a persona's goal. Accumulates
+  feature bloat without coherent direction.
+- **Persona gallery** — fictional marketing personas dressed as UX
+  personas. Names, photos, and hobbies without behavioral grounding.
+  Useless for design decisions.
+- **Goal conflation** — treating "user wants to export to CSV" as a
+  goal. That's a task. The goal is "report to their manager." The task
+  could be replaced by a better path to the goal.
+
+## Worked example
+
+For POA's deal pipeline, Cooper's approach starts with:
+
+**Primary persona**: "Operator" — the person whose full-time job is
+managing deal flow. Life goal: become a successful PE operator.
+Experience goal: feel in control of their pipeline at a glance. End
+goals per session: advance stuck deals, respond to broker inbound, log
+new conversations, identify stalled opportunities.
+
+**Secondary persona**: "Broker" — external contact. Life goal: maximize
+commissions. Experience goal: trust the platform. End goals per session:
+submit new listings, see status on submitted deals, communicate with
+Operator.
+
+**Primary wins**: the main surface is optimized for Operator. Broker
+access is a narrow, focused interface (not the Operator UI with fewer
+permissions). Dashboards emphasize stuck/stalled deals (end-goal
+triggers) over total-deals-count (vanity metric).
+
+What Cooper would NOT produce: a generic "deal management platform"
+designed for "users." A feature-grid home page. A Broker UI that's
+just Operator UI with most nav items hidden.
+
+## Sources
+
+- *About Face: The Essentials of Interaction Design* — Cooper,
+  Reimann, Cronin, Noessel, Wiley (4th ed 2014) — the foundational text
+- *The Inmates Are Running the Asylum* — Cooper (1999, rev. 2004)
+- cooper.com — Cooper consultancy (now part of Designit)
+
+## Related luminaries
+
+- **Kim Goodwin** — Goodwin provides the operational method for
+  Cooper's Goal-Directed Design; pair them always.
+- **Sophia Prater** — OOUX starts with objects; Cooper with goals. Both
+  reject feature-first. Complementary at different layers.
+- **Teresa Torres** — Continuous Discovery updates Cooper's research
+  rigor for weekly cadence.
+- **Indi Young** — Mental models research at the thinking layer below
+  Cooper's behavioral archetypes.