skills/product-discovery/SKILL.md
Validate whether a product idea is worth building before committing engineering investment. Use when someone says "should we build this", "validate this idea", "discovery", "run an experiment", "test this hypothesis", "what are the risks", "is this worth building", "feasibility check", "prototype plan", or when a team has a shaped feature or product idea and needs to assess risks and design experiments before building. Sits between product-thinker (should we?) and shaping-work (what exactly?) — this skill answers "will this actually work?" by identifying what you don't know, designing the cheapest way to find out, and defining evidence gates that justify (or kill) the investment. Also trigger when someone has a feature request and you sense high uncertainty — if the team is about to spend weeks building something nobody tested, this skill should intervene.
npx skillsauth add teambrilliant/dev-skills product-discoveryInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
Figure out whether an idea is worth building before you commit engineering time. The goal is sufficient evidence that the solution will work — not certainty, but enough to bet responsibly.
70-90% of features built without validation fail to deliver business results. Discovery exists to catch the failures early and cheap, so engineering investment goes toward ideas with real evidence behind them.
Every idea tested in discovery should cost at least one order of magnitude less than building the real thing. If engineering a feature takes 4 weeks, discovery should take days. If it takes months, discovery should take weeks.
Get clarity on what's being proposed. Read any existing artifacts — shaped work documents, PRDs, feature requests, Slack threads, customer feedback. If working in a codebase, check CLAUDE.md and related code for context.
Restate the idea as a problem to solve and a desired outcome:
If the input is a solution ("build a self-service portal"), reverse-engineer it: what problem does the portal solve? ("Partners can't onboard without calling support, costing us $X per onboarding")
Every product idea carries four types of risk. Rate each low / medium / high based on what you know right now.
Value risk — Will customers choose to use this?
Usability risk — Can users figure out how to use it?
Feasibility risk — Can we build and scale this?
Viability risk — Does this work for the business?
The risks rated medium or high are what discovery needs to address. Low risks don't need experiments — move on.
For each medium/high risk, articulate the specific uncertainty as a testable hypothesis:
We believe [specific assumption].
We'll know we're right if [observable evidence].
We'll know we're wrong if [observable evidence].
Be honest about what you can't know without investigation. Common unknowns:
| Risk | Common unknowns | |------|----------------| | Value | Will customers actually switch? Is the pain big enough? | | Usability | Can users complete the flow without help? Where do they get stuck? | | Feasibility | Can we hit the performance target? How long will integration take? | | Viability | Will legal approve this? Can support handle the volume? |
For each hypothesis, design the cheapest experiment that produces evidence. Match the experiment type to the risk:
Value experiments (will they want it?):
Usability experiments (can they use it?):
Feasibility experiments (can we build it?):
Viability experiments (does it work for the business?):
Choosing the right experiment:
Each experiment needs a clear decision point — what result means "proceed" vs "pivot" vs "stop"?
### Gate: [hypothesis being tested]
Experiment: [what you'll do]
Timeline: [days/weeks]
Proceed if: [specific evidence threshold — e.g., "4 of 5 users complete the flow without help"]
Pivot if: [evidence suggests a different approach — e.g., "users want the outcome but not this method"]
Stop if: [evidence kills the idea — e.g., "0 of 10 customers express interest in the problem"]
Evidence gates protect the team from two failure modes:
Output a structured plan. Save to thoughts/research/YYYY-MM-DD-discovery-[descriptive-name].md.
# Discovery: [idea name]
## Problem & Desired Outcome
**Problem:** [what's broken]
**Outcome:** [measurable success]
**Origin:** [where this idea came from — customer request, data insight, stakeholder ask, etc.]
## Risk Assessment
| Risk | Level | Key uncertainty |
|------|-------|----------------|
| Value | [L/M/H] | [what we don't know] |
| Usability | [L/M/H] | [what we don't know] |
| Feasibility | [L/M/H] | [what we don't know] |
| Viability | [L/M/H] | [what we don't know] |
## Hypotheses
1. [We believe X. Evidence for: Y. Evidence against: Z.]
2. [...]
## Experiments
### Experiment 1: [name]
- **Tests:** [which hypothesis]
- **Method:** [what you'll do]
- **Timeline:** [how long]
- **Cost:** [effort level — hours/days]
- **Gate:** Proceed if [X]. Pivot if [Y]. Stop if [Z].
### Experiment 2: [name]
[same structure]
## Sequence
[Which experiments to run first, which can run in parallel, dependencies between them]
## What Happens Next
- **If discovery succeeds:** Hand off to `/dev-skills:shaping-work` for detailed work definition
- **If discovery says pivot:** [what the alternative direction looks like]
- **If discovery says stop:** [document what we learned for future reference]
product-thinker → product-discovery → shaping-work → implementation-planning
"should we?" "will it work?" "what exactly?" "how technically?"
If someone brings a raw idea, suggest starting with product-thinker. If they have a clear idea but high uncertainty, this is the right skill. If the idea is low-risk and well-understood, skip straight to shaping-work.
For established companies with existing customers and revenue: experiments must protect the company's revenue, reputation, customers, and colleagues. When testing ideas that could affect real users, use conservative techniques — smaller sample sizes, internal users first, feature flags. The experiments are essential, but run them responsibly.
tools
Harvest course-corrections from the current conversation and convert them into durable fixes so the agent doesn't need the same steer next time. Use when someone says "tighten the loop", "tighten loop", "debrief this session", "session debrief", "what should I update so next time you don't…", "how can I make your life easier", "what tripped you up", "what slowed you down", or at the end of a session when the user reflects on agent friction. The scope marker is THIS SESSION / THIS CONVERSATION — that's the discriminator from sibling skills. Reads the transcript only, classifies each steer, routes to the right fix tool. NOT for: assessing repo readiness before work (use loop-check), retros on past PRs/incidents/releases (use tap-skills:retrospective), coding, or applying edits inline.
development
Capture and enforce a product's visual design language — principles and patterns that make it feel like itself. Use when the user wants to: distill design inspiration into a durable reference ("capture this design from figma", "distill this screenshot", "extract our design language", "capture design direction"), or check an implementation against the product's design language ("review design fidelity", "check against design direction", "does this match our design?", review a PR for design drift). Core signal: user points at a design source (Figma URL, screenshot, live URL) OR built UI and asks how it relates to the product's visual language. Operates on a consumer-repo `docs/design.md` — proposes diffs, never writes directly. Pairs with shaping-work, implementation-planning, implement-change, and qa-test. NOT for: generating new UI (→ frontend-design), translating a Figma design into code (→ figma-implement-design), accessibility audits (→ a11y-debugging), or token extraction.
development
Use for cross-domain strategic reasoning, approach selection, and systems-level analysis. Trigger when the user wants to: think through how to approach a problem, evaluate tradeoffs between architectural or technical approaches, sanity-check a plan or direction, understand second-order effects of a decision, get a holistic view across code/org/time dimensions, or pressure-test assumptions. The core signal is the user asking "what's the right approach?", "think about this", "what am I not seeing?", "sanity check", "tradeoffs", "how should we tackle this?", or any request for multi-level reasoning that spans product, architecture, and organization. Also use when the user needs help deciding which workflow skill to invoke next. NOT for: product/user/business decisions (→ product-thinker), work definition (→ shaping-work), file-level technical planning (→ implementation-planning), writing code, test authoring, or PR review.
development
Shape rough ideas into clear, actionable work definitions. Use this skill whenever someone has an unstructured idea that needs to become a concrete work definition — feature requests, bug reports, PRDs, customer feedback, Slack threads, stakeholder asks, or vague "we should do X" statements. Trigger phrases include "shape this", "scope this", "write a PRD", "define this work", "turn this into a ticket", "flesh this out", "spec this out", "what should we build for X", "I have an idea for...", or any rough input that needs structure before implementation can begin.