/user-needs-map

name: user-needs-map
description: "Map the needs of the people you're building or exploring for, independently of solutions, using Allen's User Needs Mapping methodology. Identifies underserved needs that feed into the Opportunity Solution Tree."
metadata:
  instruction_budget: "35"
  framework_dependency: "mycelium"
  framework_dependency_note: "This skill is designed to run within the Mycelium framework (https://github.com/haabe/mycelium). Standalone use will skip the canvas state, theory gates, and harness behavior the skill assumes. Install: /plugin install mycelium@haabe-mycelium."

User Needs Mapping

Map what users need independently of any particular solution. Discover needs through research, not assumption. Source: Rich Allen (User Needs Mapping), connected to Wardley Mapping and Team Topologies.

Preflight: Read target canvas file(s) before any Write/Edit

**Hard rule.** Before issuing `Write` or `Edit` against any `.claude/canvas/*.yml`, use the **Read tool** on that file in this session. Claude Code's Read-before-Write check requires the `Read` tool specifically — `cat`/`head`/`grep` via Bash do NOT satisfy it.

**Edit vs Write — different cost profiles** (verified 2026-05-14):

• **`Edit`** (exact-string replacement): `Read` with `limit: 1` satisfies the check at ~50 tokens. State-tracking is per-file, not per-byte — subsequent `Edit` calls work anywhere in the file. Use this for partial updates against large canvas files (e.g., `purpose.yml` at 800+ lines).
• **`Write`** (full replacement): do a **full Read** first. Write obliterates the file; you should see what you're about to replace. The `limit:1` shortcut is *not* appropriate here.

**ID-bearing entries — scan the ID space before assigning** (added 2026-05-15, v0.23.19): When adding a new component, opportunity, solution, or any other ID-bearing entry to a canvas file, run a Bash grep first to confirm the next ID in your prefix sequence is actually free:

grep -o "<prefix>-[0-9][0-9]*" .claude/canvas/<file>.yml | sort -u -t- -k2 -n | tail -3

Replace `<prefix>` with the canvas's ID prefix (`comp` for landscape, `opp` for opportunities, `sol` for solutions, `ht` for human-tasks, etc.). Then pick the next free integer, **matching the zero-padding already used in that file**. The sort is NUMERIC (`-t- -k2 -n`) rather than lexical, and that is not pedantry: a plain `sort -u` orders `ht-1` after `ht-080`, so on a canvas with inconsistent padding it reports the wrong maximum and the next ID collides. Verified on the dogfood repo 2026-08-13, where lexical sort returned `ht-1` as the highest human-task ID against an actual `ht-080`. `grep -o` is also deliberate: it matches IDs wherever they appear, including cross-references and prose, so an ID that was promised somewhere but not yet defined is not handed out twice. `validate_canvas.py` has a per-file duplicate-ID check (it reports `duplicate id '<id>'`) that catches the failure on CI, but a duplicate can persist in the working tree for days if CI isn't run between edit and discovery; that happened on 2026-05-15, when a duplicate ID was created in `landscape.yml`.

Original failure mode: anti-pattern #7 instance #5, 2026-05-09 — agent conflated Bash `head` with the Read tool, lost ~14k tokens to a Write-fail → remedial-full-Read → re-Write loop. The `limit:1` discipline (graduated 2026-05-14, v0.23.18) prevents the second-order cost where the agent *correctly* follows the rule but full-Reads every time. The ID-scan discipline (graduated 2026-05-15, v0.23.19) prevents the related class where the agent reads enough of the file to satisfy the Edit check but not enough to see existing ID assignments — kin to anti-pattern #8 (Stale State Read).

If this skill writes to multiple canvas files, register each one first (limit:1 for Edit-only paths; full Read for Write paths) AND ID-scan any prefix you intend to assign.

See `${CLAUDE_PLUGIN_ROOT}/engine/agent-operating-contract.md` *Canvas writes — Read before Write* for the canonical rule.

When to Use

• During L2 Opportunity discovery
• When building initial understanding of user landscape
• When validating whether team/service boundaries align with user needs
• When the OST needs a stronger needs foundation

Workflow

1. Identify User Types

Who interacts with or is affected by this product/service?

• Direct users (hands-on)
• Indirect users (affected by outcomes)
• Internal users (staff, support, ops)

2. Extract Needs from Research

From interviews, observations, support tickets, and behavioral data, extract discrete need statements. Read for the need, not the term: the same need is said many ways, and some are never said at all (see Unrecognized below). Method: `${CLAUDE_PLUGIN_ROOT}/engine/reading-for-meaning.md`.

**Format**: "As a [user type], I need to [action/capability], so that [outcome/benefit]"

**Three dimensions** (from Christensen JTBD, applied to Allen's framework):

• **Functional**: What they need to accomplish practically
• **Emotional**: How they need to feel during and after
• **Social**: How it affects their relationships, status, perception

**Rules**:

• Needs come from RESEARCH, not brainstorming or stakeholder wishes
• Each need must cite at least one evidence source
• Separate needs from solutions: "I need to know my order status" not "I need email notifications"

3. Score Needs (Importance vs Satisfaction)

*Source: **Ulwick** (Outcome-Driven Innovation) for the opportunity algorithm and the importance/satisfaction questions — verified in `What Customers Want` (2005) and `Jobs to be Done: Theory to Practice`. **Allen states the same two questions and explicitly defers the method**: "detailed outcome validation and prioritisation techniques go beyond what we'll cover in this book... Frameworks like Outcome Driven Innovation (ODI) provide a structured way to use this data."*

> **Attribution corrected 2026-09-20 after reading Allen in full.** The previous note read "Allen's