@thebassclef/lite 1.1.0 → 1.2.0-alpha.1

package/dist/lite/.claude/skills/docs-sync/SKILL.md

@@ -0,0 +1,188 @@
+---
+tier: lite
+name: docs-sync
+description: "Sync adopter-facing bassclef docs to the GitHub Wiki. Mirrors the bassclef-docs-sync.yml workflow locally. Use when the workflow is wedged or the operator wants a manual full-sync."
+problem: "Adopter-facing bassclef docs drift from source. Wiki gets stale."
+value: "Syncs adopter-facing bassclef docs to the GitHub Wiki. Mirrors the bassclef-docs-sync.yml workflow."
+inputs: [Optional --dry-run flag]
+outputs: [Wiki pages updated, Diff report, Sync log]
+user_invocable: true
+disable_model_invocation: false
+---
+
+# `/docs-sync` — Operator-invocable wiki sync
+
+The `bassclef-docs-sync.yml` workflow fires automatically on push-to-main when allowlisted paths change. This skill is the manual escape hatch: invoke locally to sync the wiki without pushing, or to force a full re-sync when the workflow is stuck.
+
+## When to invoke
+
+- The bassclef-docs-sync workflow is wedged (rare; surfaces via `80-workflow-staleness.sh` once it's re-armed)
+- Operator wants to validate wiki state without waiting for the next push
+- Doing a force full-sync after wiki was manually reorganized
+- Initial wiki bootstrap (workflow exits clean if wiki not initialized; this skill walks the operator through init)
+
+## When NOT to invoke
+
+- Routine — let the workflow do its job; don't double-sync
+- Inside an autonomous /longrun (the workflow fires anyway when the step's PR merges)
+- For non-allowlisted files (out of scope; if it should be synced, edit `standards/docs-sync-allowlist.md` and add the path to the workflow)
+
+## Procedure
+
+### Step 1 — Read the allowlist + confirm scope
+
+Read `standards/docs-sync-allowlist.md`. Decide whether this run is:
+- **changed-only** (default): sync files modified since the wiki's `HEAD` commit
+- **full-sync**: sync every allowlisted file regardless of mtime
+
+State the choice in agent output before proceeding.
+
+### Step 2 — Verify wiki repo exists
+
+```bash
+gh api repos/sunj-labs/bassclef/wiki 2>&1 | head -5
+```
+
+If wiki not initialized: stop. Tell operator to open the Wiki tab once on GitHub UI, then re-invoke this skill. Don't attempt to create it via API; the bootstrap requires UI interaction once per repo.
+
+### Step 3 — Clone wiki locally
+
+```bash
+git clone https://github.com/sunj-labs/bassclef.wiki.git /tmp/bassclef-wiki
+```
+
+If clone fails with auth error, stop. Operator needs to ensure their `gh` is authenticated with `repo` scope.
+
+### Step 4 — Identify files to sync
+
+For changed-only:
+```bash
+cd /tmp/bassclef-wiki
+LAST_WIKI_COMMIT_TS=$(git log -1 --format=%ct)
+cd $REPO_ROOT
+git log --since="@$LAST_WIKI_COMMIT_TS" --name-only --pretty=format: | sort -u | grep -E "(standards/project-directory-layout|docs/bassclef-mental-model|docs/bassclef-overview|^README|docs/hooks-index|standards/bassclef-source-config|standards/vendor-bindings|architecture/decisions/ADR-|.claude/skills/.*/SKILL|.claude/rules/.*\.md)"
+```
+
+For full-sync: enumerate every file matching the allowlist patterns.
+
+### Step 5 — Map source paths to wiki page names
+
+Mirror the workflow's mapping (see `.github/workflows/bassclef-docs-sync.yml` for the authoritative case statement):
+
+| Source | Wiki page |
+|---|---|
+| `standards/project-directory-layout.md` | `Directory-Layout.md` |
+| `docs/bassclef-mental-model.md` | `Mental-Model.md` |
+| `docs/bassclef-overview.md` | `Overview.md` |
+| `README.md` | `Home.md` |
+| `docs/hooks-index.md` | `Hooks-Index.md` |
+| `standards/bassclef-source-config.md` | `Bassclef-Source-Config.md` |
+| `standards/vendor-bindings.md` | `Vendor-Bindings.md` |
+| `architecture/decisions/ADR-NNN-*.md` | `ADR-NNN-*.md` (preserve filename) |
+| `.claude/skills/<name>/SKILL.md` | `Skill-<name>.md` |
+| `.claude/rules/<name>.md` | `Rule-<name>.md` |
+
+### Step 6 — Strip frontmatter + write to wiki
+
+For each file, strip YAML frontmatter only if present (first line is `---`); otherwise pass through unchanged. Many files (most ADRs, some skills, some rules) start with `# Title` and have no frontmatter — passing them through `awk 'BEGIN{fm=0} /^---$/{fm++; next} fm<2{next} {print}'` produces empty content because `fm` never reaches 2.
+
+```bash
+SRC=$REPO_ROOT/<source>
+DST=/tmp/bassclef-wiki/<wiki-page>
+if head -1 "$SRC" | grep -q '^---$'; then
+  awk 'BEGIN{fm=0} /^---$/{fm++; next} fm<2{next} {print}' "$SRC" > "$DST"
+else
+  cp "$SRC" "$DST"
+fi
+```
+
+### Step 7 — Commit + push wiki
+
+```bash
+cd /tmp/bassclef-wiki
+git config user.name "operator"
+git config user.email "$(git config --global user.email)"
+git add -A
+git commit -m "docs-sync: manual sync from main@$(cd $REPO_ROOT && git rev-parse --short HEAD)"
+git push
+```
+
+### Step 8 — Report what synced
+
+Output a flash + tweet summary naming each synced file + its wiki page. Operator returns to a scannable list.
+
+### Step 9 — Cleanup
+
+```bash
+rm -rf /tmp/bassclef-wiki
+```
+
+Stateless skill; no local artifacts persist.
+
+## Output format
+
+```markdown
+## /docs-sync — [changed-only OR full-sync]
+
+**Flash:** [synced N pages | wiki not initialized | no changes detected]
+
+**Tweet:** [one-line sharpener about what happened]
+
+### Synced
+- source-path → wiki-page-name
+- source-path → wiki-page-name
+
+### Skipped (non-allowlisted)
+- source-path — reason
+
+### Cross-references (advisory)
+- file-X references file-Y; both synced
+```
+
+## Rules
+
+- **Never modify wiki content beyond mapped source paths.** If a wiki page exists for a file not in the allowlist, leave it alone — that page was manually authored and isn't bassclef's concern.
+- **Never sync frontmatter.** The frontmatter is parser-targeted metadata, not operator narrative. Strip before writing.
+- **Don't delete wiki pages.** Even if a source file is deleted, leave the wiki page in place. Operator decides whether to delete it via the Wiki UI.
+- **Don't run inside /longrun.** The GHA fires on each step's merge anyway. Manual invocation inside an active /longrun is redundant.
+
+## Adopter mode (per bassclef#1265)
+
+Adopters that opt in via `.claude/bassclef-configs.jsonc` `wiki_sync.enabled: true` get this skill PLUS a vendored workflow + allowlist. The skill reads the config block at runtime and adapts:
+
+- `wiki_sync.enabled: false` (default) — skill warns "wiki_sync disabled in bassclef-configs.jsonc; no sync target. Enable + re-vendor templates first."
+- `wiki_sync.enabled: true` + workflow + allowlist present — skill works as documented above against the adopter's own allowlist
+- `wiki_sync.enabled: true` + workflow missing — skill surfaces BLOCK: "wiki_sync enabled but `.github/workflows/bassclef-docs-sync.yml` not vendored; run /onboard-repo refresh to install."
+
+Templates to vendor (one-time per adopter):
+
+- `presence/install/bassclef-docs-sync.template.yml` → adopter's `.github/workflows/bassclef-docs-sync.yml`
+- `presence/install/docs-sync-allowlist.template.md` → adopter's `standards/docs-sync-allowlist.md`
+
+After vendoring, adopters edit three surfaces in the workflow to match their repo's paths (the `on.push.paths` glob, the Filter step's case-glob, the Sync step's source-path → wiki-page mapping). The allowlist file is the operator-readable source-of-truth alongside.
+
+## Composes with
+
+- `bassclef-docs-sync.yml` workflow (this skill's authoritative twin)
+- `standards/docs-sync-allowlist.md` (the allowlist contract)
+- `presence/install/bassclef-docs-sync.template.yml` (adopter-vendored workflow per bassclef#1265)
+- `presence/install/docs-sync-allowlist.template.md` (adopter-vendored allowlist seed per bassclef#1265)
+- `.claude/bassclef-configs.jsonc` § `wiki_sync` (config block read at runtime)
+- `.claude/rules/session-artifacts.md` § Wiki-as-we-go discipline (methodology rule the workflow enforces)
+- Future `/hooks` skill (also reads from an allowlist)
+
+## Sources read
+
+- `.github/workflows/bassclef-docs-sync.yml` — workflow this skill mirrors
+- `standards/docs-sync-allowlist.md` — allowlist contract
+- `docs/iteration-bets/2026-05-13-s3-retirement-docs-sync-hooks-index.md` — parent goal (c-package WU-5)
+- `docs/iteration-bets/2026-06-20b-cold-adopter-mechanism-inheritance.md` — WU-2 of follow-on goal (bassclef#1265 adopter inheritance)
+
+## Closes
+
+- WU-5 of c-package bet — provides manual fallback when the GHA can't fire
+- WU-2 of bet 2026-06-20b (bassclef#1265) — adds adopter-mode awareness so the skill works for adopters that opt in via `wiki_sync` config
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.

package/dist/lite/.claude/skills/eisenhower/SKILL.md

@@ -0,0 +1,273 @@
+---
+name: eisenhower
+description: "Turn open tickets and PRs into a scored Eisenhower matrix \u2014 do, schedule, delegate, delete. Anchors 'important' to a goal you name first, so the sort has meaning. Two modes: default (current repo) and --cross-repo."
+problem: "Backlog fills with tickets and PRs. Priorities blur. What to do first is unclear."
+value: "Turns open tickets and PRs into a scored Eisenhower matrix \u2014 do or schedule or delegate or delete."
+inputs: [Optional persona ref or launch goal]
+outputs: [4-quadrant matrix, Score per ticket, Recommended pickup order]
+tier: lite
+maturity: alpha
+user_invocable: true
+disable_model_invocation: false
+modes: [default, --cross-repo, --dry-run]
+composes_with: [value-prop, kiss, sprint, longrun, promote, personas]
+depends_on: []
+authoring_luminaries:
+  primary:
+    - ryan-singer
+    - alan-cooper
+    - tony-ulwick
+---
+
+# /eisenhower
+
+## What you get
+
+A scored list of your open tickets and PRs. Four buckets. Q1 fires today. Q2 goes on the calendar with a time budget. Q3 items batch up. You automate them or hand them off. Q4 gets closed. The scoring anchors to a goal you name first. No anchor, no score.
+
+## When to use it
+
+- Sprint planning — you have 50+ open items and need to pick 5
+- Backlog audit — the queue has drifted from any current goal
+- After a strategy pivot — re-score against the new target
+- Before a long solo session — decide what to skip first
+
+## When NOT to use
+
+- Under 5 open items — the sort adds ceremony without payoff. INSTEAD: pick the top item and start.
+- Emergency prod fire — fix it now, score after. INSTEAD: run `/diagnose` and ship the fix.
+- Group brainstorm — this is a solo scoring pass, not a group tool. INSTEAD: run a workshop with sticky notes.
+- No stated goal — the matrix collapses without an anchor. INSTEAD: run `/state-a-problem` first, then come back.
+
+## FAQ
+
+### How is this different from just sorting my backlog?
+
+Sorting alone tells you nothing about WHY one item ranks higher. This skill anchors the sort to a goal you state first. The same ticket can land in Q2 for "ship v1" and Q4 for "reduce tech debt." Without the anchor, "important" becomes personal taste.
+
+### What if I have no stated goal?
+
+The skill stops and asks for one. Three shapes work. An active goal from your state file. A persona target. Or a custom sentence like "cut infra bill by half." Silence returns no score.
+
+### How does the skill decide urgent vs important?
+
+Urgent means: does this block prod, revenue, or a hard deadline? Important means: does this move the stated goal forward? A ticket can be urgent but not important. That is Q3, delegate. Or important but not urgent — Q2, schedule.
+
+### Does it write anywhere?
+
+Default is read only. It prints the sorted table to your terminal. The `--dry-run` mode is explicit no-write. Optional follow-on: if 5+ items in Q3 share a shape, the skill can propose one `/promote` ticket to automate the class.
+
+### What time budget goes on Q2 items?
+
+You set it. The skill borrows Ryan Singer's Shape Up rule. Q2 items get a fixed time budget with variable scope. If a Q2 item cannot fit in a fair budget, it is Q4 in disguise. Too big to schedule. Not worth shaping.
+
+### Can I re-score without restarting?
+
+Yes — call the skill again with a new goal. The frame changes what "important" means. The same tickets can re-sort. Useful when you shift from "polish for launch" to "recover from incident" mid-cycle.
+
+## Details below the fold
+
+### Step 1 — Anchor the goal
+
+The skill prompts you with three shapes:
+
+```
+Before I score, name the goal I'm scoring against. Pick one:
+
+1. Current in-flight goal — read from your state file if present
+2. Persona target — which user does this cycle's work serve?
+3. Custom sentence — you type it. Examples:
+   - "ship v1.0 by end of Q1"
+   - "reduce onboarding drop-off from 40% to 20%"
+   - "cut infra bill by half"
+
+The frame decides what "important" means. A ticket that is Q2 for
+"onboard the first paying customer" may be Q4 for "clean up tech
+debt". Silence here means no score — I stop and ask again.
+```
+
+If a state file exists, the skill reads it. Adopters may have `PLAN.md`, `ROADMAP.md`, or a bassclef `docs/whereami.md`. The skill offers the top item as a default. You can accept, override, or type a fresh goal.
+
+INSTEAD of moving on without a goal: the skill blocks. Silence at this step returns exit 1.
+
+### Step 2 — Pull the work
+
+Reads open items from the sources you have:
+
+- `gh issue list --state open --limit 200` (current repo default)
+- `gh pr list --state open --limit 100` (current repo default)
+- Under `--cross-repo`, it prompts for the repo list
+- Fallback when `gh` is not authed: reads a paths list you provide
+
+Each item captures number, title, labels, age, last activity, and comment count.
+
+### Step 3 — Score each item
+
+For each item, the skill asks two questions:
+
+- **Urgent?** Does this block prod, revenue, security, or a hard deadline in the next 2 weeks?
+- **Important?** Does this move the anchor goal from Step 1 forward?
+
+The scoring rule per eisenhowermatrix.com:
+
+```
+if (blocks_prod OR blocks_revenue OR hard_deadline_2wk) urgent++;
+if (advances_stated_goal) important++;
+```
+
+Quadrant assignment:
+
+| Urgent | Important | Quadrant | Action |
+|---|---|---|---|
+| Yes | Yes | Q1 | DO NOW |
+| No | Yes | Q2 | SCHEDULE (with time budget per Ryan Singer) |
+| Yes | No | Q3 | DELEGATE, BATCH, or AUTOMATE |
+| No | No | Q4 | CLOSE — leave off the calendar |
+
+One line of rationale per item. Ties get flagged for your review, not split.
+
+### Step 4 — Emit the scan table
+
+Output format:
+
+```
+GOAL: <the anchor you stated at Step 1>
+SCORED: <N> items across <M> repos
+
+## Q1 — Do now (X items)
+- #123 — title — <one line why urgent + important>
+- #124 — title — ...
+
+## Q2 — Schedule (Y items)
+- #125 — title — time budget: <duration> — <why important>
+
+## Q3 — Delegate / batch / automate (Z items collapsed)
+Shape 1: <N items> all doing <shape> — automation candidate
+Shape 2: <M items> all needing <owner> — delegate as a batch
+Individual items: ...
+
+## Q4 — Close (W items)
+- #126 — title — 87 days old, no comments — CLOSE with rationale
+- #127 — title — no path to advance the goal — CLOSE
+```
+
+### Step 5 — Optional follow-on
+
+If Q3 surfaces 5+ items in the same shape, the skill offers to draft one `/promote` ticket. That ticket proposes automating the class. You accept, edit, or skip.
+
+The skill leaves ticket closure to the operator. All actions need your confirmation.
+
+INSTEAD of closing tickets on your behalf: the skill prints Q4 items as hints for your review.
+
+### Modes
+
+| Mode | What it does |
+|---|---|
+| `default` | Score open items in the current repo |
+| `--cross-repo` | Prompts for repo list, scores across all named repos, unified table |
+| `--dry-run` | Same as default but suppresses the optional `/promote` follow-on offer |
+
+## Examples
+
+### Input
+
+```
+$ /eisenhower
+
+Before I score, name the goal I'm scoring against. Pick one:
+> ship v1.0 by end of Q1
+```
+
+### Output
+
+```
+GOAL: ship v1.0 by end of Q1
+SCORED: 42 items across 1 repo
+
+## Q1 — Do now (2 items)
+- #234 — payments fail on Safari — blocks revenue, ships in v1.0 path
+- #241 — auth session leak — security, blocks v1.0 launch
+
+## Q2 — Schedule (8 items)
+- #189 — new checkout flow — time budget: 2 weeks — v1.0 core value
+- #198 — landing page rewrite — time budget: 1 week — v1.0 launch surface
+[...]
+
+## Q3 — Delegate / batch / automate (12 items collapsed)
+Shape 1: 6 items all "update dependency X" — automation candidate (dependabot)
+Shape 2: 4 items all customer support requests — delegate to support team
+
+## Q4 — Close (20 items)
+- #45 — refactor color palette — 127 days old, no comments, unrelated to v1.0
+- #67 — try new logging library — exploration, off the v1.0 path
+[...]
+
+5 items in Q3 share the "update dependency" shape. Draft a /promote for
+automation? (y/n)
+```
+
+## Anti-patterns and INSTEAD
+
+| Anti-pattern | INSTEAD |
+|---|---|
+| Score without an anchor goal — "important" becomes personal taste | Stop and ask for the goal. Silence at Step 1 returns exit 1. |
+| Score against "engineering excellence" or "code quality" — too broad to sort by | Pick a concrete outcome. A launch. A metric. A customer commitment. |
+| Treat every backlog item as Q2 because closing feels wrong | Q4 exists for a reason. Old tickets with no goal-fit go to CLOSE hints. |
+| Auto-close Q4 items on the operator's behalf | The skill only prints hints. Q4 output waits for your review. |
+| Skip the time budget on Q2 items | A Q2 item without a budget is Q4 in disguise. INSTEAD: assign a budget or move it. |
+
+## Composes with
+
+- `/value-prop` — the anchor goal is often the value prop for a launch or milestone
+- `/kiss` — the output stays plain English; `/kiss words --rewrite` runs on the final table
+- `/sprint` — sprint proposals read the Eisenhower sort to pick the top N items
+- `/longrun` — long-session prep uses quadrant scoring to shape scope options
+- `/promote` — Q3 pattern batches become promote tickets
+- `/personas` — the persona-target shape at Step 1 reads persona files if present
+
+## Distinct from
+
+- `/sprint` — proposes NEXT WORK based on state; this skill SCORES ALL OPEN WORK by goal fit
+- `/roadmap-reconcile` — reconciles roadmap docs against shipping reality; this skill scores tickets against a goal
+- `/state-a-problem` — drafts a problem statement (an anchor goal input); this skill CONSUMES that anchor
+- `/value-prop` — drafts value proposition prose (an anchor goal input); this skill CONSUMES it
+- Manual backlog grooming — same shape but without the goal anchor, so it drifts into personal taste
+
+## Rules
+
+- Skill requires a stated goal before scoring. Silence at Step 1 returns exit 1.
+- Skill leaves ticket closure to the operator. Q4 output is a hint for review.
+- Skill stays read-only in default mode. Optional `/promote` follow-on needs explicit "yes."
+- Skill shows the anchor goal at the top of the output. Every reader sees the frame.
+- Skill attaches a one-line rationale per item. Silent quadrant assignment is a bug.
+- Skill treats tickets over 60 days old with no comment activity as strong Q4 hints unless the goal frames them otherwise.
+
+## Test cases
+
+- **Empty backlog** — 0 open items → output "no items to score" and exit 0
+- **No stated goal** — operator sends empty response at Step 1 → exit 1 with "no score without goal"
+- **All Q1** — 10 items, all urgent + important → output flags "everything cannot be Q1" and asks for a re-score
+- **Goal shift mid-cycle** — same 42 tickets scored against "launch v1" then "recover from incident" → sort differs
+- **Q3 pattern surfacing** — 6 tickets all "update dep X" → skill offers a `/promote` for automation
+- **No `gh` auth** — falls back to paths list from operator; scoring still works
+- **Persona target shape** — operator says "onboarding new users" → skill loads persona file if present, uses persona goal as anchor
+
+## Sources read
+
+- eisenhowermatrix.com/templates/eisenhower-matrix-for-software-developers — Q1-Q4 shape and scoring rule
+- `.claude/luminaries/ryan-singer.md` — time budget with variable scope for Q2 items
+- `.claude/luminaries/alan-cooper.md` — persona-first anchor for the goal statement
+- `.claude/luminaries/tony-ulwick.md` — outcome baseline for measuring "important"
+- Memory `feedback_eisenhower_test_against_persona_launch.md` — "important" scoped to market goal, not general engineering hygiene
+
+## Why this skill exists
+
+Every backlog audit collapses without a stated goal. "Important" has no meaning unless anchored. The failure mode is quiet. Operators score tickets by personal taste. Or by engineering aesthetics. Or by whichever conversation happened last. Not by fit to a stated target. The scored list looks clean. It reflects the scorer, not the goal.
+
+The Eisenhower matrix is 70 years old. The four quadrants are well known. What operators miss is that the frame decides the sort. A ticket that is Q2 for one goal is Q4 for another. Without the anchor, the matrix ships noise.
+
+This skill mechanizes the anchor. Step 1 blocks until you name the goal. The rest runs the sort against that goal. If you shift the goal, you re-run. The matrix stays honest because the anchor stays visible.
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on the final scored table before you return it. See `standards/skill-output-discipline.md` for the contract.

package/dist/lite/.claude/skills/empathy-map/SKILL.md

@@ -0,0 +1,168 @@
+---
+tier: lite
+name: empathy-map
+description: "Draft Dave Gray's 7-section empathy map for one persona (Goal, See, Say, Do, Hear, Think and Feel, Pains, Gains). Two modes: light (5 min per band, workshop pace) and deep (15 min per band, research pace). Cite transcript lines."
+problem: "Personas ship without lived context. Downstream product decisions miss what the user sees or feels."
+value: "Dave Gray's 7-section empathy map for one persona. Goal + See + Say + Do + Hear + Think + Pain plus Gain."
+inputs: [A persona name from the personas file]
+outputs: [Empathy map with 7 sections filled, Persona insight anchors]
+user_invocable: true
+disable_model_invocation: false
+modes: [light, deep]
+composes_baseline: [dave-gray, alex-osterwalder]
+---
+
+# /empathy-map — Persona empathy map (Dave Gray canvas)
+
+Draft the empathy map for one persona. Sensor bands (See, Say, Do, Hear) are populated from real interview or observation data. Inference bands (Think and Feel) sit on top of the sensor bands with each inference citing the sensor line it rests on. Pains and Gains close the map.
+
+Two modes on a single axis: how much time you have per band.
+
+- **light** (default): 5 minutes per band, workshop pace. Good for a solo operator sitting with fresh interview notes and 45 minutes of writing time. Produces a scannable map ready for downstream skills (`/interview-me`, `/lean-canvas`, `/pre-mortem`).
+- **deep**: 15 minutes per band, research pace. Full interview-transcript walkthrough with per-quote timestamps. Produces a research-grade artifact suitable for adopter-persona docs and downstream design decisions.
+
+## Sources read
+
+- `.claude/luminaries/dave-gray.md` — full luminary with 2017 updated canvas + signature quote + anti-patterns
+- `.claude/luminaries/tony-ulwick.md` — JTBD complement (Ulwick asks WHAT the user is trying to accomplish; Gray asks WHO the user IS while trying)
+- Operator direction 2026-07-07 evening — split empathy-map from `/interview-me` per composability; standalone skill callable from multiple upstreams
+
+Note: `.claude/luminaries/alex-osterwalder.md` is declared in `composes_baseline` but has not yet shipped as a full-depth luminary file. When it ships, this skill will read from it for the Value Proposition Design incorporation reference.
+
+## Sources used
+
+### Dave Gray — Empathy Map Canvas (2017 updated)
+
+Seven sections in clockwise order [ref: `.claude/luminaries/dave-gray.md` §Core methods]:
+
+1. **Goal** — WHO is the map about + what specific goal or observable behavior
+2. **See** — environmental observations; what the persona sees around them
+3. **Say** — verbatim quotes from interviews or field notes
+4. **Do** — observable actions and behaviors
+5. **Hear** — what others tell the persona (boss, team, market)
+6. **Think and Feel** — inferred cognitive and emotional state; each inference cites a sensor band
+7. **Pains** — frustrations, blockers, measures of failure
+8. **Gains** — desired outcomes, measures of success
+
+(The "8 sections" count reflects Pains and Gains as separate bands; Gray's canvas visualizes them as two bottom bands under the central rectangle.)
+
+### Alex Osterwalder — Value Proposition Design (2014)
+
+The Value Proposition Canvas incorporates the empathy map as the customer-profile half. Jobs / Pains / Gains framing maps directly to Gray's Pains and Gains bands. When `/empathy-map` output feeds `/lean-canvas` or a value-proposition workshop, the Pains and Gains bands become the customer-profile input.
+
+## When to use
+
+- **You just finished interviews** — synthesize the transcripts before design decisions rot
+- **A design argument is stuck** — the team is arguing "what users want" without evidence; fill the map together and see what surfaces
+- **You're kicking off a new adopter** — pair with `/interview-me` to walk the discovery flow end-to-end
+- **You're running `/pre-mortem` and need a persona-affected-by-failure lens** — fill an empathy map for the user who suffers when the ship goes wrong
+
+INSTEAD of running the skill without interview data: interview first. An empathy map filled from imagination is a persona sketch, not a research artifact. Sarah Gibbons at NN/g: "Sparse maps signal more research is owed" — the empty band is the finding.
+
+## Procedure
+
+### Common to both modes
+
+1. **Ask for the Goal** — one sentence: WHO is the map about + what specific outcome anchors the map (e.g., "small-team CTO shipping an internal ops tool in 6 weeks")
+2. **Ask for input source** — pasted interview notes, transcript timestamps, observation log, or "I only have my own knowledge from working with them" (flag this openly and continue with the sensor-band-empty finding)
+3. **Walk sections in clockwise order** — Goal → See → Say → Do → Hear → Think and Feel → Pains → Gains
+4. **Enforce sensor-band-first discipline** — inference bands (Think and Feel) filled AFTER sensor bands carry evidence
+
+### Light mode (5 min per band)
+
+- Ask 3-5 open-ended questions per sensor band
+- Take operator answers verbatim; capture quotes in Say without paraphrase
+- For Think and Feel, ask "based on what you just wrote in See/Say/Do/Hear, what do you infer about their internal state?" — capture and cite the sensor line
+- For Pains and Gains, ask "what did they name as frustrations?" and "what did they name as measures of success?"
+- Total time: ~45 minutes
+
+### Deep mode (15 min per band)
+
+- Ask 8-12 open-ended questions per sensor band with follow-up probes ("can you say more about that? what was the context?")
+- For Say, tag each quote with a transcript timestamp or field-note reference
+- For Do, distinguish "observed once" from "observed as a pattern"
+- For Think and Feel, require every inference to cite the specific sensor line(s) it rests on
+- For Pains and Gains, distinguish "named by the persona" from "inferred by the researcher" — mark the difference
+- Total time: ~2 hours
+
+## Output
+
+Structured markdown artifact saved at `docs/personas/<slug>-empathy-map.md`:
+
+```markdown
+---
+persona_slug: small-team-cto
+goal: "Ship a working ops tool in 6 weeks that the team actually uses."
+input_source: "45-min interview 2026-07-07; transcript at docs/interviews/2026-07-07-cto.md"
+mode: light
+date: 2026-07-07
+---
+
+# Empathy map — small-team CTO
+
+## Goal
+Ship a working ops tool in 6 weeks that the team actually uses.
+
+## See
+- Open-plan office; other engineers' screens visible all day
+- Slack messages piling up during focus blocks
+- Ops team using a spreadsheet for the current process
+
+## Say
+- "We ship Friday." [interview 12:34]
+- "I keep watching other CTOs move faster with worse code." [interview 22:10]
+
+## Do
+- Opens sandbox at start of every workday
+- Reviews yesterday's shipping metrics before standup
+- Deploys 3-5 times per day
+
+## Hear
+- Team asks for X
+- PM asks for Y
+- Board asks for Z (three demands often conflict)
+
+## Think and Feel
+- Worries the team will hit rate limits mid-quarter [inferred from Say 22:10 + Hear "board asks for Z"]
+- Feels responsible for both technical and product direction [inferred from Do "deploys 3-5 times per day" + Hear "PM asks for Y"]
+
+## Pains
+- Every new tool requires an onboarding session; loses 2 days per new hire (named)
+- Watches other CTOs ship faster with worse code (named)
+
+## Gains
+- Wants team velocity to compound (named)
+- Wants to spend more time on architecture and less on triage (named)
+- Wants tools that work on day one (named)
+```
+
+## Called by
+
+`/empathy-map` is a leaf skill. Larger skills call it as a step:
+
+- `/interview-me` — Step 3 (empathy map fills pains/gains/needs from interview data)
+- `/lean-canvas` — customer-segment and problem boxes read from Pains and Gains
+- `/pre-mortem` — persona-affected-by-failure lens uses this map to imagine who suffers when the ship goes wrong
+- `/personas` (if it exists) — the empathy map is the underlying research shape for an adopter-persona doc
+
+## Anti-patterns it prevents
+
+Per `.claude/luminaries/dave-gray.md` §Anti-patterns:
+
+- **Fiction in the Say band** — skill refuses to write in Say without a transcript or field-note reference. INSTEAD: if operator supplies none, the band stays empty and the emptiness is flagged as the finding.
+- **"I know the user" skip** — light mode default asks operator to write down tacit knowledge in the sensor bands. INSTEAD of skipping: if the writing surfaces claims operator cannot cite, that IS the finding.
+- **Persona-mapping without interviews** — if operator names "I have not interviewed this persona." INSTEAD: skill produces sensor bands marked "research needed" and downstream skills read the flag.
+- **Inference-only maps** — Think and Feel section requires sensor-band citations. INSTEAD of filling inference first: fill sensor bands from observation; then infer with each inference citing the sensor evidence it rests on.
+
+## Refs
+
+- Ticket #657 — this skill's filing
+- Ticket #653 — `/interview-me` (composes with this skill)
+- Ticket #655 — `/pre-mortem` (may compose with this skill)
+- Bet 2026-07-07a — this skill's ship vehicle
+- Luminary file `.claude/luminaries/dave-gray.md` — full-depth anchor
+- Rule `.claude/rules/skill-composition-declarations.md` — the composability discipline this skill honors
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.