product_market_fit v1.0.0

name: product_market_fit description: "Run a product-market-fit check that ends in a decision: score the Sean Ellis survey honestly with a confidence interval and segment scores, read the cohort retention curve shape, code the open answers and interview signals against a fixed codebook, and make the push, persevere, narrow, or pivot call with all the evidence on one page. Ships a tested scoring and retention tool, a survey and coding reference, a one-page read template, and a worked read for a small product. Use when someone asks whether a product has product-market fit, how to run or score the Sean Ellis test, why growth feels forced, whether to scale acquisition or keep iterating, or how to read a retention curve. Not for pricing research, not for a general market sizing exercise, and not a substitute for talking to users when there are too few users to survey."

Product-Market Fit

Purpose

Most product-market-fit claims rest on one warm signal: a few happy users, a good week of signups, a survey somebody scored generously. This skill runs the check the hard way and ends in a call somebody has to own.

Three kinds of evidence go on one page:

• Stated dependence: the Sean Ellis survey, scored exactly the way Ellis ran it, with the sample size and interval printed next to the score so a thin sample cannot dress up as a verdict.
• Behaviour: the cohort retention curve, judged by shape. A curve that flattens has a retained base. A curve still falling to zero contradicts any survey result.
• Coded words: the open survey answers and interview notes, coded against a codebook written before the results are seen, so the story the team tells itself comes from the users' words and not from hope.

The deliverable is a one-page read with one of five calls: PUSH, PERSEVERE, NARROW_AND_PERSEVERE, PIVOT, or INSUFFICIENT_EVIDENCE. A check that cannot make a call says why and names the evidence it still needs.

Definitions used here, from the primary sources in references/survey-and-coding.md: Marc Andreessen, 2007: product-market fit means being in a good market with a product that can satisfy that market. Sean Ellis: a leading indicator is the share of users who would be very disappointed if they could no longer use the product. Ellis benchmarked nearly 100 startups and found the dividing line at 40 percent.

Workflow

1. Fix eligibility before anyone sees a score

Survey only users who have experienced the core of the product. Ellis's rule, as Superhuman applied it: used the product at least twice in the past 2 weeks. Adapt the activity test to the product's natural cycle (a monthly product needs a monthly window) and write the rule down in the read.

• Exclude staff, test accounts, and users who signed up but never reached the core action.
• Never survey the same user twice for a scored round. Superhuman was careful about this because repeat respondents distort the benchmark.
• Keep a fourth answer, no longer use, in the form if the tool needs it. Those respondents leave the denominator. They are not current users and counting them as disappointed or not disappointed both corrupt the score. Report how many were excluded.

2. Run the four questions, word for word

From the Superhuman survey, with the product name swapped in:

1. How would you feel if you could no longer use [product]? Very disappointed, somewhat disappointed, not disappointed.
2. What type of people do you think would most benefit from [product]?
3. What is the main benefit you receive from [product]?
4. How can we improve [product] for you?

Do not soften question 1, do not add a five-point scale, and do not ask whether users like the product. The question measures dependence, and changing the words changes the measure. Send it after the core experience, not at signup.

3. Score it honestly

Put responses in a CSV with columns respondent_id, segment, feeling, benefit_code, improvement_code and run:

python3 scripts/pmf_check.py survey responses.csv

The tool prints the score, a 95 percent Wilson interval, and the honesty flags. Rules it enforces:

• The score is very disappointed divided by eligible respondents. Somewhat disappointed never counts toward it.
• Under about 40 eligible respondents the result is directional only. That anchor comes from Superhuman's practice: they had 100 to 200 users to poll and noted directionally correct results start around 40 respondents. Directional means it can guide interviews. It cannot carry a push or a pivot call.
• A wide interval that straddles 40 percent means the honest sentence is "the score is consistent with fit and with no fit", not "we are basically at 40".
• Segment scores print with their own n. A segment under 10 eligible respondents is a lead for interviews, never a narrow call.

4. Segment before concluding anything

The overall score hides the only useful question: fit for whom?

• Read segment scores in the tool output. If the overall score misses 40 percent but one real segment clears it, fit exists in a narrower market. That is a different decision from no fit.
• Build the high-expectation customer from the clearing group, the way Superhuman did: take only the very disappointed respondents, read their answers to question 2, and write the profile in their words. Happy users describing who would benefit most are usually describing themselves.
• If no segment clears 40 percent, that is a finding too. Write it plainly.

5. Code the words against a codebook

Code question 3 and question 4 answers, and any interview notes, using the codebook method in references/survey-and-coding.md. Write the codebook before reading results in bulk.

• The main benefit is the most common benefit code inside the very disappointed group only. Benefits named by users who would not miss the product do not define the product.
• The blockers that matter come from one filtered group: somewhat disappointed respondents whose stated main benefit matches the main benefit above. Their question 4 answers, ranked by count, are the conversion list. Superhuman found its top blocker (no mobile app) exactly this way.
• Not disappointed respondents get no vote on the roadmap. Their requests describe a product for somebody else, and acting on them bends the roadmap toward users who will leave anyway.
• Code interviews the same way: problem severity, current workaround, what they tried before, and whether they pulled the product in or were pushed. Pull signals (came looking, paid without a sales push, expanded use on their own) weigh more than polite praise.

6. Read the retention curve shape

Export a cohort curve: one consistent definition, period or unbounded retention, never a mix. Period retention counts a user in a period only if they were active in that period. Unbounded counts them if they were active in that period or later. Pick by the product's natural rhythm: regular use suits period measures, irregular use suits unbounded. Mixing the two invents a shape that does not exist.

Put period and retained_pct (optionally cohort and cohort_size) in a CSV and run:

python3 scripts/pmf_check.py retention retention.csv

The tool averages cohorts per period, fits the tail slope on the last 3 periods, and names the shape:

• flattening: tail slope inside the flat band. A retained base exists at that level. Judge the level against a floor the team states for its own product type. No universal level benchmark exists, and this skill does not invent one.
• rising_tail: check for returning users (a smile pattern) and rule out a cohort mix change before celebrating.
• slow_decay or decaying: no stable base at this horizon. More acquisition pours into a leaking bucket.
• headed_to_zero: final level near zero and still falling. Behaviour votes no, whatever the survey said.
• insufficient: fewer than 4 periods. Extend the window before judging shape.

7. Make the call

Run the combined read:

python3 scripts/pmf_check.py report --product NAME --survey responses.csv --retention retention.csv --out read.md

The tool applies these decision rules, and the one-page read shows the evidence for whichever call comes out:

• PUSH: overall score at or above 40 percent, at least 40 eligible respondents, and retention flat, rising, or absent. Scale acquisition aimed at the segment that produced the score, and keep scoring new rounds because scores often fall as the audience widens.
• NARROW_AND_PERSEVERE: overall under 40 percent, but a segment with at least 10 eligible respondents clears 40 percent. Serve that segment first with positioning, onboarding, and roadmap. Other segments become later markets, not current problems.
• PERSEVERE: under 40 percent with a workable engine. Split the roadmap in half, as Superhuman did: half doubles down on the main benefit, half fixes the ranked blockers from the filtered group, cheap and high impact first. Resurvey new users only.
• PIVOT: score under this skill's 20 percent working floor, no segment clears 40 percent, and retention is flat-out bad or absent. The pairing of this product and this market is not working. Change the market, the problem, or the product core, then rerun only after users have experienced a changed offer.
• INSUFFICIENT_EVIDENCE: fewer than 40 eligible respondents, fewer than 4 retention periods with a disputed call, or survey and retention in open conflict that nobody has explained. The read names the missing evidence and how to get it.

Threshold honesty: 40 percent is the Ellis benchmark. The 20 percent pivot floor, the segment minimum of 10, and the retention slope bands are this skill's working rules, chosen to force a decision and printed as working rules in the tool output. They are not published benchmarks and the read must not present them as such.

8. Deliver the one-page read

Use templates/one-page-read.md. One page, evidence first, call in the largest type, next move with an owner and a date for the resurvey round. If the call is push, the read also names the risk that comes with it: the score was earned on today's narrower audience.

Output Contract

A finished check delivers:

• The one-page read: product, date, eligibility rule, eligible n, score with its 95 percent interval, segment table with n per segment, main benefit, ranked blockers from the filtered group, retention shape with tail slope and final level, the call, and the next move.
• The response CSV and retention CSV the read was computed from, so anyone can rerun the tool and get the same numbers.
• The codebook used for benefit and improvement codes.
• A resurvey date and the rule that the next round polls new users only.

Operating Rules

• Never report a score without its n and interval on the same line.
• Never round a 38 percent score up into a fit claim, and never average away a segment that clears the bar.
• Never survey users before they have experienced the core product, and never resurvey the same users for a scored round.
• Never act on feature requests from the not disappointed group during a fit check.
• Never mix period and unbounded retention in one curve, and never judge a curve on fewer than 4 periods.
• Never present this skill's working thresholds as published benchmarks. The only published benchmark used here is Ellis's 40 percent.
• If there are too few users to survey, say so and run problem interviews instead. Five users is an interview study, not a survey, and dressing it as one misleads everyone who reads the number.