pain-signal-miner

name

pain-signal-miner

description

Find and rank evidence-backed startup problems and product opportunities from recent public complaints, requests, workarounds, switching behavior, and spending signals. Use when Codex needs to research a market or niche, discover problems worth solving, validate whether an idea addresses repeated pain, analyze competitor gaps, identify underserved workflows, define a small MVP wedge, or create a sourced startup-opportunity report instead of brainstorming unsupported ideas.

Pain Signal Miner

Turn a market, audience, workflow, or startup idea into a ranked set of problems supported by current public evidence. Distinguish observed pain from inferred demand and unknown market size.

Read references/research-framework.md before researching or scoring. Read references/report-artifact.md before creating the final report.

Workflow

1. Define the research boundary

• Identify the market, actor, job to be done, geography, language, time horizon, and desired opportunity type.
• Narrow broad markets to a specific actor and workflow before searching.
• For an existing idea, define the core pain assumption and disconfirming evidence.
• Infer missing context only when safe and label the inference. Ask one concise question when ambiguity would materially change the research.

2. Build a pain-signal search plan

Search current public sources for several signal types:

• direct complaints and repeated frustration
• requests for tools, alternatives, or missing features
• manual workarounds, spreadsheets, scripts, assistants, and copy-paste processes
• switching, churn, cancellation, or competitor dissatisfaction
• spending, hiring, consultants, or paid tools used to manage the problem
• triggers that make the pain urgent now

Use multiple query angles and source types. Prefer original pages over search snippets. Record the source URL, visible date, source type, actor, job, evidence, and whether the signal is observed or inferred.

3. Research responsibly

• Use public, intentionally shared information only.
• Do not bypass access controls, login walls, paywalls, robots restrictions, or rate limits.
• Do not use leaked data, private groups, data brokers, or sensitive personal information.
• Avoid identifying or targeting people through protected traits, health conditions, financial hardship, political beliefs, sexuality, religion, or other sensitive attributes.
• Quote minimally and paraphrase by default. Keep any excerpt short and link the original source.
• Do not count reposts, copied reviews, or the same incident on multiple sites as independent evidence.

4. Normalize and cluster

Convert raw signals into a consistent structure:

• actor
• job or desired outcome
• trigger
• failure or friction
• current workaround
• consequence or cost
• spending or buying proxy
• source and date

Cluster signals by shared actor, job, and failure mode. Split clusters that have different buyers or different willingness-to-pay dynamics. A strong cluster should contain at least three independent signals across at least two source types; otherwise label it preliminary.

5. Score without inventing demand

Score each cluster using the bundled framework:

• frequency
• urgency
• spending signal
• workaround cost
• reachability
• evidence confidence

Do not treat complaints alone as proof that people will pay. Keep market size, acquisition cost, retention, and willingness to switch as unknown unless directly evidenced.

6. Convert problems into testable opportunities

For every qualified cluster define:

• narrow audience and painful job
• current workaround and its cost
• smallest viable product wedge
• plausible pricing or business-model hypothesis
• reason the timing may be favorable
• fatal assumption
• 48-hour validation test

Prefer a small wedge that removes one expensive workflow over a broad platform idea.

7. Produce the report

Lead with the evidence, not the methodology. Use this order:

1. Market verdict — whether the research found strong, weak, or contradictory pain.
2. Best opportunity — highest-scoring cluster and why it matters.
3. Opportunity leaderboard — score, audience, pain, workaround, spend signal, wedge, and risk.
4. Evidence ledger — original public sources and signal dates.
5. Repeated patterns — language, triggers, workarounds, and switching barriers.
6. 48-hour validation plan — actions that could disprove the top opportunity.
7. Unknowns — what public research cannot establish.

Create a standalone HTML report unless the user explicitly requests chat-only output:

1. Write structured JSON using references/report-artifact.md.
2. Run scripts/generate_report.py <analysis.json> <report.html>.
3. Save the report in the workspace outputs/ directory.
4. Verify the opportunity cards, source links, score breakdowns, validation plan, and unknowns.
5. Return a clickable absolute file link in the final response so it opens from Codex.

Modes

• quick: Return up to three clusters from a focused scan.
• standard: Return up to five clusters with a mixed-source evidence ledger.
• deep: Return up to eight clusters with stronger source diversity and contradiction analysis.
• idea-validation: Test one startup idea and actively search for disconfirming evidence.
• competitor-gaps: Mine reviews, feature requests, switching complaints, and missing workflows.
• niche-discovery: Start from an audience or industry and identify underserved jobs.

Use standard by default.

Quality bar

• Link every material claim to an original public source.
• Prefer three strong clusters over ten generic ideas.
• Make dates, source diversity, contradictions, and weak evidence visible.
• Separate observed pain, inferred demand, and unknown economics.
• Include disconfirming evidence instead of forcing a positive verdict.
• End with a falsifiable test, not a vague recommendation to build.