The Spec

Agree it in writing, before any code

A spec is where you and Claude write down exactly what you're building and both nod. It's cheap to fix a sentence here. It's expensive to fix a finished feature that was built on a misunderstanding.

The napkin → The brief → The spec
What a good one looks like

Retention Pulse, specced

This is the spec that grew straight out of the brainstorming brief: the same project, sharpened into an agreement. Click "why this is here" on any section to see what makes a spec good.

Retention Pulse — Feature Spec
docs/specs/retention-pulse.md
01Goal
Surface members who are quietly slipping away, early enough that the owner can act and save them before they cancel.
What makes it good
A good spec opens with the goal restated in one line. Everything below has to serve it. If a feature doesn't, it gets cut right here, not after it's already built.
02In scope
Read members, class visits and payment status. Detect members who've gone quiet or whose payment is about to lapse. Rank them by money at risk. Show them on one colour-coded triage board.
What makes it good
Scope is a short, plain list. Anyone reading it knows exactly what's being built, with no room to quietly assume more.
03Out of scope
No messaging members. No replacing the CRM. No editing member data. Read-only.
What makes it good
The out-of-scope list is what stops a build sprawling. A good spec is as clear about what it won't do as what it will. This is the line most people skip, and the reason builds balloon out of control.
04The data
From the studio software, through the browser: member list, class visit history, payment status and next payment date. Read-only access.
What makes it good
Name the exact data and where it comes from. Saying read-only sets a boundary Claude will respect, so it never tries to change live records.
05The rules
"Quiet" = no attendance in the last 14 days. "Lapsing" = payment due within 7 days. Rank by next payment amount. Colour by severity: black, red, orange, yellow, green.
What makes it good
This is the heart of the spec. Notice the fuzzy words from the brief, "quiet" and "urgent," are now concrete numbers. A good spec turns judgment into something testable, so you and Claude mean the same thing by the same word.
06The view
One board, sorted by urgency, colour-coded, glanceable in seconds. Works on both mobile and desktop.
What makes it good
Describe the one surface and how it's used in real life (glanced at each morning). That context quietly shapes a hundred small choices Claude would otherwise have to guess.
07Done looks like
The owner opens it each morning and sees exactly who to call today. Nothing to dig for.
What makes it good
A testable finish line. This is how you both know when it's done, instead of polishing forever or stopping too early.
And here's mine

Our actual spec for Retention Pulse

The clean version up top is the shape. This is the real spec that actually built the app: my own, longer and messier. Beside each part, why it earns its place.

§1 · Problem & North Stars

Start with the problem, not the feature

Coffs pays Recovr about $300 a month to spot slipping members before they cancel, and they want to drop it: opaque score, glitches, and it overwhelms a stretched manager. The job: flag slipping members, give the plain-English why, and link to Grow so the human writes the message. No AI messaging. North stars: beat Recovr, and delightfully impress Coffs. Prototype-first, craft over coverage.

Why it's good
"I open with the real problem and a real competitor, not a wish-list. The north stars are the tie-breaker: every later call gets checked against 'does this beat Recovr and wow Coffs?' If it doesn't, it's out."
§2 · The two-layer model

Name the architecture up front

Layer 1
Eligibility router: who's a member we'd retain, and which surface do they belong on?
↓
Layer 2
Risk engine: of the active members, who's slipping, how badly, how winnable?
Why it's good
"Splitting it in two is the whole architecture. The first attempt skipped the router and graded a borrowed list, so the numbers meant nothing. Naming the layers here stops that happening again."
§3 · Eligibility router

One testable rule, not a brittle list

Package Category = "Memberships"
AND Status IN (Active, Scheduled)
AND Package Price > 0

A $0 price means comp, so it's excluded. That one trick catches staff, family and ambassadors without naming them all. (Category drifts plural or singular per studio, so match both.)

Why it's good
"One rule beats a list of package names that breaks the moment a studio renames something. You only land a rule this clean by writing it down before you build."
§5 · The severity ladder

Concrete numbers, colour kept apart from rank

Blackpaying + absent 60 or more days
Redpaying + absent 21 to 59 days (winnable)
Orange14 to 20 days out, or a steep frequency drop
Yellowflagged (late or early cancels), still showing up
Greenhealthy, paying
Newown lane: activate, not "we miss you"

Colour = severity. Rank = winnability.

Why it's good
"Day-numbers make 'slipping' testable instead of a vibe. And I keep colour (how bad) apart from rank (who to call first), because collapsing them wastes your morning on the worst case instead of the one you can actually save."
§7 · UX surfaces

Their calm, our honesty

The why moves off the card and into a click-in member peek; the cards go light; a calm Home becomes the front door. It's Recovr's structure (bounded glance, one thing per card, depth behind a click) with our honest substance: every flag traces to a real signal, never a black-box score.

Why it's good
"I took what made Recovr feel calm and dropped what made it dishonest. The peek is where the real why lives, one click away, instead of crammed onto every card."
§9 · Wording standard (locked)

Lock the exact words

No em-dashes in client copy. Pipes for heading separators. Locked phrasings so terms never drift: "X days since last class", "down A to B visits this month", "X late cancels in Y", "next payment $X on DATE".

Why it's good
"Pin the language and the app never sprouts five ways of saying the same thing. Yes, it's the same no-dashes rule this whole guide follows."

The full spec runs twelve sections: data layer, the score, actions, access, positioning, build state. This is the spine. It ends on one line: once it's locked, turn it into the plan. Which is exactly the next tab.

Agreed

Once you both nod, the spec becomes the plan

The spec says what you're building. The next step breaks it into the small, ordered steps that actually get built, one verifiable chunk at a time.

Up next · The Plan