Files
skills/skills/discovery-framing/SKILL.md
T
mathiasandClaude Opus 5 56a947b2a0 refactor(plugin)!: ship as a Claude Code plugin, one dir link per harness
Skills move to skills/<name>/SKILL.md and the repo gains both manifests, so
it is now a marketplace hosting exactly one plugin whose root is the repo
root (source: "."). Claude Code installs it from git; no symlinks involved.

Why: install.sh wired the library into every consuming repo as an ABSOLUTE
symlink to $CHECKOUT_DIR. The checkout moved three times, most recently when
local-dev@1966d5a dropped the embedded .skills/ copy, and nothing migrated
the links — 243 dangling links across 12 repos, hidden from git by the
**/.claude/skills/ ignore rule. Worse, ~/dev spans two path roots
(/Users/mathias on the iCloud-shared Macs, /home/mathias on koala), so an
absolute link stored there is broken on one side by construction. Re-running
the installer cannot fix that; only removing the mechanism can.

install.sh keeps the harnesses with no plugin system and drops from 42 links
per harness to one directory link, via the convergent ~/.agents/skills
convention that Pi and OpenCode both read:

  ~/.agents/skills          -> $CHECKOUT_DIR/skills
  ~/.config/crush/skills    -> ~/.agents/skills
  ~/.config/opencode/skills -> ~/.agents/skills

wire_claude_repo is deleted outright rather than gated behind a flag — on a
mixed-root fleet it cannot be made correct. Antigravity and Vibe targets go
too; both unused. CHECKOUT_DIR keeps its host-local default deliberately:
pointing it into ~/dev would put a git working tree inside iCloud with two
concurrent writers.

Taskfile drops five near-identical wiring loops (they had already drifted)
and delegates to install.sh. `task check` gains frontmatter validation, a
stray-root-entry gate, and manifest/tag version parity — the loose
secret-hygiene.md sat unloadable for months because nothing checked layout.

Verified: claude plugin validate . passes clean; a probe skill loaded as
skills:zzprobe through --plugin-dir; task check green at 42 skills.

Refs: #23
Bump-Type: minor

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BeAp5LTscnz2W7Ubt4eJ6m
2026-08-23 14:29:51 +02:00

8.9 KiB
Raw Blame History


name: discovery-framing description: Run the discovery / framing phase of product innovation — define and quantify a focused customer problem BEFORE any solution exists. Four movements: understand the problem space, learn about customers, identify and size problems, decide pursue/table/kill. Produces a problem brief per prioritized opportunity. Use when an idea is still vague, when someone is jumping to solutions before the problem is validated, when scoping early research, or when deciding which problems are worth pursuing. Trigger phrases include "frame the problem", "discovery", "problem statement", "is this worth building", "early research", "opportunity sizing", "we have an idea for", "how might we", "what problem are we solving".

Discovery / Framing

The phase before solutioning. Goal: define and quantify a focused customer problem, tied to a specific target segment, validated with external evidence — so that later investment rides on a real problem, not a pet idea. Products built on a validated problem have a materially higher success rate; solving an unvalidated problem builds something that solves nothing.

This is the de-identified pattern. When run for a named client, the wrapper (their phase names, internal tools, region structure, named teams) stays in the client boundary.

Pairs with stage-gate-review (this is the Frame→Concept gate's content) and the brain principle on solutions-looking-for-problems. Killing a bad problem here is the cheapest kill you will ever make.


The four movements

1. Understand the problem space   →  2. Learn about customers
         ↓                                      ↓
4. Decide: pursue / table / kill  ←   3. Identify & size problems

Typical envelope: weeks, not months; cheap. The whole point is to de-risk before spend.

1. Understand the problem space (the ecosystem)

Map the field before judging any idea. You are not validating a solution — you are learning the terrain.

  • Ecosystem analysis — top trends, market size (the whole pie, not your slice), key players (end users, customers, intermediaries), competitors and their gaps.
  • Value-exchange map — list every player; for each, the qualitative + quantitative value flowing to/from them; score it. A scalable ecosystem has roughly equal value per player — lopsided value = it won't scale across the chain. This is the single most overlooked check.
  • External-forces scan (PESTL + localization) — Political, Economic, Social, Technological, Legal, plus local/regulatory constraints that break the business model in a given market.

2. Learn about customers and end-customers

  • Personas / design targets — behaviours, needs & values, pain points, gains. Keep them universal where possible (cut across segments), specific where it matters.
  • Journey maps — steps & touchpoints, emotional valence per step, pain points and opportunity areas. Separate the customer journey from the end-customer journey.
  • Assumptions → hypotheses — dump everything you believe true about the target (quantity over quality), then prioritize on a risk × certainty grid: attack the assumptions that are high risk AND low certainty first. Sort each into Desirability (do they want it?), Feasibility (can we build it?), Viability (can we make money?). Convert each prioritized assumption into a testable hypothesis: "If we do X, then Y will happen" — falsifiable, specific outcome.
  • Validate externally — research with real customers/end-customers (interviews, focus groups, surveys, diaries). Record per persona: assumption → learning → validated/invalidated. External validation is non-negotiable — a problem confirmed only internally is not confirmed.

3. Identify and size the problems

  • Problem statement — one tight form: "[who] needs a way to [need], but [compelling insight from research]." The insight cites where/how the opportunity actually manifests, not a guess.
  • Total Addressable Problem (TAP) — not market size. Market size is the pie-in-the-sky figure. TAP = (what would they pay to solve this specific problem) × (how many have it), summed across use cases. A subset of the market, honestly bounded. Sizing the problem — not the market — is what makes prioritization real.

4. Determine next steps

  • Prioritize by TAP × strategic fit.
  • Pursue / table / kill — every problem gets one verdict. Kill is a first-class output, not a failure; a tabled problem is parked with its reason.
  • How-Might-We — reframe each pursued pain point as an open question to spark solution ideation. Use verbs, not nouns — never pre-pack a solution into the HMW. ("HMW increase awareness…" not "HMW build an app that…").
  • Problem brief — one per pursued opportunity (see below). This is the deliverable that carries into the solutioning gate.

The Problem Brief (required deliverable)

A problem brief, not a solution brief. Fields:

  1. Problem — "We believe [user/customer/market] needs a way to [need], because/but/ surprisingly [insight]." Quantitative proof where possible.
  2. Customer — who has it; segment specifics; their pain points / desired gains.
  3. End-customer (if different) — who you're ultimately innovating for.
  4. Why it matters — to them and to you; what you observed that makes this a priority.
  5. Ecosystem — relevant signals, localization needs, competitive/comparative landscape.
  6. Total Addressable Problem — the bounded value of the problem.
  7. Thought-starters / HMW — reframed questions, no solutions.
  8. Desired value & outcomes — impact if the problem were solved.
  9. Strategic benefit — how success is measured for the business; strategy fit.

If a brief drifts into describing a solution, it has failed — send it back to the problem.


Anti-patterns

  • Solution smuggling — an HMW or brief that already names the answer. The discovery is over before it began.
  • Internal-only validation — "we all agree it's a problem." That is conviction, not evidence. See stage-gate-gate-killers.
  • Market size as problem size — quoting a $XXbn TAM to justify a narrow bet.
  • Skipping the kill — every idea "has potential." A discovery phase that never kills a problem is theatre.
  • Lopsided value exchange — a solution that enriches one player and starves another; it will not scale no matter how good the UX.

Operator judgment (hard-won)

Compressing discovery by stakes

  • High-stakes bet: run all four movements hard — especially external customer research and the riskiest-assumption tests. Don't thin the validation.
  • Low-stakes bet: keep movement 1 (ecosystem) + movement 3 (problem statement + a rough size). Size with TAM / SAM / SOM instead of a full Total Addressable Problem build.
  • Customer research can be skipped or AI-simulated for low stakes — a well-framed agent, prompted as the target persona, can give a directional read fast. Treat this as a cheap directional signal only — it is not external validation and never clears a high-stakes desirability assumption. Use it to decide whether real research is worth doing.

The bar for "externally validated"

No fixed floor — case by case. The invariant is the posture, not the count: go looking for disproving evidence, not reinforcing evidence. A problem survives discovery when you tried to kill it with real external input and couldn't — not when N people nodded along. (Same disease as a faked gate — see stage-gate-gate-killers.)

Tell for solution smuggling

The solution is described crisply and confidently, but the moment you ask whose problem and how do you know, the answer goes fuzzy — the need is vague, the validation is hand-wavy. Crisp solution + fuzzy problem = reverse-engineered justification. Stop and reframe.

War-story patterns (de-identified)

  • Sized big, fizzled in reality. A problem that scored a large TAP/TAM but never converted to sustained real-world usage. Lesson: problem size ≠ adoption. A big addressable problem measures willingness to care, not willingness to change behavior. Add a "would they actually switch/use it repeatedly?" test before trusting a large size.
  • Tabled/iceboxed a valid problem others then won. A real problem killed or parked on weak conviction or bad timing, which competitors later executed well. Lesson: the kill is not free. Killing protects against sunk cost, but a wrong table is also a cost — record why you tabled and a signal that would reopen it, so a right problem killed for the wrong reason can come back.

Named instances of both war stories are client-tagged and held out of this public skill pending client-store decision. The transferable lesson lives here; the wrapper stays out.