VALUEPROP.md

An agent-readable definition of how a business gets money.

Your README.md tells an AI agent what the code does. Nothing in your repo tells it what the business does — what's sold, who pays, and which surfaces turn intent into revenue. So agents (and contractors, and agencies) either guess, or ask, or optimize things that don't matter.

VALUEPROP.md fixes that with one markdown file at the repo root:

• What we sell — offers as falsifiable sentences, not slogans.
• Who buys and why — the buyer, the pain, the trigger.
• When and where they buy — the moment intent becomes contact.
• Conversion points — the machine-parsable core: every revenue-bearing surface, with a stable id, the analytics event it must emit, a falsifiable hypothesis, and an evidence-backed status (hypothesized → instrumented → validated, with regressed when reality disagrees).
• Assumptions and open questions — the guesses, stated as guesses.

Conversion points are fenced YAML blocks, so tooling can join them to analytics by event and to everything else by id. An agent editing your site can see which surfaces are load-bearing for revenue. A CI check can refuse a deploy that breaks an instrumented conversion point. An experiment can declare exactly which hypothesis it's trying to move.

Findings, never promises: a status may only move up the lifecycle with evidence. A VALUEPROP.md full of aspiration is worse than none.

Start here

• SPEC.md — the format, the conversion-point contract, the parsing rules.
• skills/valueprop-interview — a Claude skill that interviews the owner (and refuses vague answers) to generate a conforming file.
• examples/ravenflight.io — a real one, guesses and all.

Roadmap

• valueprop check — CI validator: schema conformance, then "does every instrumented point still emit its event."
• Analytics wiring — a snippet/package that maps declared events onto PostHog / Cloudflare Analytics.
• Continuous revalidation — scheduled re-testing of validated hypotheses in prod, auto-flagging regressed.

---

Maintained by RavenFlight — we audit conversion surfaces for a living, and this file format is how we make the results durable. Spec is v0.1 and open to issues/PRs.