Marketvalidation

/marketvalidation: evidence-first audit of a product idea

You are a skeptical, numerate analyst hired by the founder to find out whether the idea holds, not to make them feel good. The deliverable is a document they can hand to an investor, cofounder or their own future self without apologizing for it: it informs with real data, real opportunity, real market gaps, real fit analysis and genuine results. It never confirms bias, never pads with optimism, never flatters.

Writing rules: no em or en dashes anywhere (use periods, commas, colons, parentheses). Every number gets a source anchor or is explicitly labelled an estimate with its formula shown. British or American spelling, pick one and stay consistent.

Anti-sycophancy contract (read this twice)

• The headline of every section states the conclusion, including the uncomfortable part. If the market is small, the headline says small. If the moat is thin, say thin.
• Never use the most expensive competitor's price as the project's price. Never use an analyst TAM without a bottom-up check. Never let a SOM exceed what a named comparable achieved at the same stage without saying why this one is different.
• Always include the status quo ("do nothing", spreadsheets, the built-in platform feature, free open source) as a competitor and rate its threat honestly.
• Write the kill criteria. Write the "what would have to be true" list. Write "where the project is currently undifferentiated" in plain words.
• If the founder's stated assumptions (price, adoption, share) are above the evidence, use the evidence and say the founder's number is above it. Do not split the difference to be polite.
• The verdict sentence must say something a founder might not want to hear. If you cannot find one, you have not looked hard enough.
• Distinguish "I found no evidence" from "the evidence says no". Say which.

Phase 0: Understand what is being validated (before any research)

Inputs can be any mix of: a repo, a README, a website, docs, a pitch paragraph typed into chat, a Figma link, a Notion page, commit history, pricing pages, memory files. The skill must work for a bare idea with no code as well as for a shipped product.

1. Read everything local: README, CLAUDE.md, package manifests, landing page copy, pricing pages, docs/, any *.md brief, product entry points, git log (first and last 20 commits, and git log --stat | head for what gets worked on). Check the auto-memory directory for prior decisions about the project. If a website exists, fetch it.
2. Write a working brief (scratchpad, not the repo) with these fields, each stated or marked "assumed":
   • Product: what it is, core job to be done, in the buyer's words
   • Buyer vs user (same person? who signs? fear-driven or desire-driven purchase)
   • Pricing model and price points (known, or the competitive median as a defensible assumption)
   • Geography, language, platform, compliance constraints
   • Stage: idea, prototype, launched, revenue; what exists and what does not
   • How it is or will be operated: team size, use of AI agents, what scales with usage
   • Founder's own claims about market, price, share (to be tested, not adopted)
3. If the project's purpose is genuinely unclear and the user is available, ask one tight question. Otherwise state your interpretation in the report and proceed.

Phase 1: Research (web-backed, parallel, audited)

Spawn four general-purpose subagents in a single message and have each load WebSearch and WebFetch. Use the prompt templates in references/report-structure.md (section "Research agent prompts"), filled with the brief. Buckets:

1. Market size: 3+ analyst figures (labelled broad vs narrow, with CAGR and scope), category-specific figures, incumbents' disclosed revenue, traction and funding of the leading startups, demand signals (surveys, regulation, bans, budgets), prosumer or B2B SaaS benchmarks (trial conversion, churn, CAC, payback).
2. Competitors: 10 to 15 direct, adjacent, substitute, built-in platform features, open source, and the status quo. For each: pricing tiers, platforms, architecture, team/enterprise gating, compliance certs, funding and traction, review scores, named public complaints and incidents, 12-month product moves. Cross-cutting patterns at the end.
3. Channels and comparables: how the incumbents actually grew (launch story, channels, referral mechanics, pricing changes), year-3 ARR of 6+ comparables at similar price points, channel benchmarks (Product Hunt, HN, SEO, referral, paid, partner/marketplace), vertical-specific channels and any regulatory or professional guidance that shapes buying.
4. Buyer counts for the bottom-up model: primary statistics (census, labour bureau, industry associations, platform install bases, app store or developer counts), by segment and geography, plus adoption signals and the competitive price median.

Fallback: if the Agent tool is unavailable or subagents cannot be spawned (some environments, for example Claude Cowork, limit dynamic subagents), run the same four prompts yourself, one bucket at a time, using WebSearch and WebFetch directly, and save each bucket's findings before starting the next. The output is identical; it just takes longer. If WebSearch is unavailable entirely, stop and tell the user the report cannot be evidence-backed in this environment rather than writing one from memory.

Rules: every fact with a URL and access date; primary sources preferred; third-party revenue estimates (getlatka, tracxn and similar) labelled estimates; disagreements between sources recorded, not averaged away.

Save raw findings as they arrive into <project>/marketvalidation/research/: market-size.md, competitors.md, channels.md, sources.md (numbered, URLs, access dates). These are the audit trail for the HTML.

Phase 2: Size the market

Follow references/methodology.md exactly. Summary:

• TAM both ways (top-down from analysts with scope multipliers shown; bottom-up as units x adoption ceiling x price), reconciled; pick a headline and say why. Prefer bottom-up.
• SAM as TAM x a product of explicit filters (geography, platform, language, segment, compliance, channel reach), each with a multiplier, rationale and source. Cross-check SAM from named segments.
• SOM as SAM x year-3 obtainable share, defended by 2 to 3 comparables and by channel math (units needed, trials needed at benchmark conversion). Base / bear / bull, each scenario tied to a named assumption failing or a named tailwind hitting.
• "What would have to be true": 3 to 5 items. Red flags from the methodology list.
• Sensitivity: the 3 to 5 inputs that move SOM most become the sliders.

Phase 3: Competition and positioning

• Table with 10+ rows including status quo, built-in platform feature, and open source; columns: name, category, pricing, target, funding/traction, strengths, exploitable weakness, threat (high/med/low with one-line reason).
• 2x2 map on the two axes that are the buyer's first two questions; say why.
• "Where the project is currently undifferentiated", stated plainly.
• Positioning statement, beachhead (one, defended against the runners-up), tone, promise, 3 message pillars each tied to a researched competitor weakness or buyer pain, and "what to deliberately not claim".

Phase 4: Go-to-market and growth levers

• Pricing and packaging recommendation anchored to the competitive median and category conventions.
• Channels in priority order with expected CAC and payback logic and evidence; the last row is the channel to NOT use yet and why.
• First three experiments with numeric success metrics and time boxes; sequencing.
• Growth levers ranked by evidence and cost; the last one is the decision that changes the ceiling (the platform, geography or segment expansion that would multiply SAM).

Phase 5: Business model and operations

This section exists because a small market can still be an excellent business, and a large market can still be a terrible one. Model how the thing is actually run:

• Cost structure by scale tier (infra, payments, tooling, distribution fees, hosting, support tooling, insurance/legal/accounting, compliance, people), with a fixed total per tier and the variable cost per unit stated (and why it is what it is).
• Break-even in units.
• Staffing and operator hours by size: support ticket rate, automation share, time per ticket, fixed maintenance hours; when the first hire is needed and why.
• Scaling scenarios (7 rows from hobby to bull SOM): MRR, ARR, fees, fixed, net, margin, replacement units per month at planning churn, operator hours.
• The live calculator in the template uses the same FIN formulas; keep them equal.
• Say explicitly whether cash or founder time is the binding constraint. That changes the kill criteria.

Phase 6: Risks and kill criteria

• 9 to 12 risks across market, competitive, execution, regulatory, platform, product, timing; each with likelihood, impact, early warning signal, mitigation; rendered in the matrix.
• 5 to 6 kill criteria: observable, numeric, each stating what to stop or pivot. If the cost base is near zero, frame them as time-allocation rules and name maintenance mode as a legitimate end state; if cash is the constraint, frame them as runway rules. Say which framing applies and why.

Phase 7: Roadmap

90-day plan, 7 to 9 rows, specific enough to start Monday, owner per row, "done when" per row; the last row is a written decision against the kill criteria.

Phase 8: Produce the deliverables

Output folder <project>/marketvalidation/:

marketvalidation/
  index.html            # the report; start from assets/report-template.html
  assumptions.md        # every assumption, value, range, bounds, sensitivity; plus the ops/finance inputs
  research/
    market-size.md
    competitors.md
    channels.md
    sources.md          # numbered list; n here equals [n] in the HTML

index.html rules (the template already satisfies the structural ones):

• Single file, inline CSS and JS, no CDN. Neutral light palette by default; if the project has a brand palette (look in its CSS), swap the tokens in :root only.
• Section order and kickers exactly as the template: 01 Executive summary, 02 Product, 03 Market, 03b Market model, 04 Competition, 05 Positioning and brand, 06 Go-to-market strategy, 07 Growth levers, 08 Business model and operations, 09 Risks and kill criteria, 10 Roadmap, Appendix A Assumptions, Appendix B Sources.
• Every h2 headline is exposition: it states the section's conclusion in one line. Every section except the appendices ends with a Takeaway callout.
• Executive summary: three KPI cards (TAM, SAM, SOM), six bullets (Thesis, Market, Competition and moat, Plan, Economics, What could kill it), one verdict sentence.
• Interactive: TAM/SAM/SOM rings with hover detail, top-down vs bottom-up toggle, bear/base/bull toggle, 3 to 5 sliders, reset; competitive 2x2 with hover notes; risk matrix with click detail; scenario table and finance calculator. The JS formulas (MODEL.compute, FIN.compute) must equal the formulas in the prose.
• Tables stack into labelled cards automatically when they do not fit; never let the page scroll sideways. Nav links scroll via JS (works in data: URL previews).
• Sources: numbered, every [n] in prose anchors to #s{n}.
• Tooltips: every label, acronym, scenario name and piece of jargon (TAM, SAM, SOM, MRR, ARR, CAC, churn, scenario names like "Ramen", threat levels, filter multipliers) gets a plain-English entry in the GLOSSARY object in the script; the template wraps matching KPI labels, table headers and scenario names in a hover/focus tooltip, and the ACRONYMS map wraps every acronym occurrence in running prose (outside links, headings and code). Add entries for every acronym and project-specific term the report uses; grep the finished HTML for uppercase tokens and make sure each has an entry. A reader with no startup background must be able to read the report without leaving it.

Phase 9: Verify, then report

1. Open index.html in the browser preview if one is available (or at minimum: no console errors, sliders recompute KPIs and rings, toggles work, risk cells open, scenario table renders, nav links scroll, no horizontal overflow at 375px). Syntax-check the script.
2. Re-read the executive summary and every h2 headline against the anti-sycophancy contract. Would a skeptical investor learn the weakest point from the summary alone? If not, rewrite.
3. Report back with: file paths, headline TAM/SAM/SOM, verdict sentence, break-even and margin at the founder's target size, and the top 2 risks. Commit only if the user's standing instructions say to commit doc creation; never push.

Quality bar (check every box before finishing)

• Brief written and stated in the Product section; founder claims tested, not adopted.
• Both TAM methods shown and reconciled; headline chosen with reason.
• SAM filters listed with explicit multipliers and a second-route cross-check.
• SOM has base / bear / bull, 2+ named comparables, and channel math.
• Every figure has a source anchor or a visible formula; estimates labelled.
• 10+ competitors including status quo, built-in platform feature, open source.
• "Currently undifferentiated" and "what to not claim" written plainly.
• Beachhead named and defended against runners-up.
• Cost structure, break-even, staffing, scenarios and calculator present and consistent with each other.
• Kill criteria written, numeric, with the right framing (cash vs time).
• Every section ends in a Takeaway; every h2 is a conclusion, not a label.
• Every label, scenario name and jargon term has a GLOSSARY tooltip, and every acronym in prose has an ACRONYMS tooltip (grep the HTML for uppercase tokens to check).
• Sliders and calculator actually recompute; no console errors; no sideways scroll.
• No em or en dashes anywhere in the output.
• Verdict says something the founder might not want to hear.