The compass, not the engine

AI will build anything. It won't tell you what's worth building.

Half an hour of honest scoping saves weeks of building in the wrong direction. Work through six focused steps and walk away with a one-page brief, and a mind map, you can hand to your AI or to a coach.

See an example brief

checkpulse — privacy-first web analytics in one binary — scoped this way. Yours comes out in the same shape.

# Privacy-first web analytics in a single self-hosted binary ## Problem Google Analytics is bloated and needs a consent banner. I just want to know which posts get read and where readers come from. ## Out of scope Funnels, session recording, multi-user logins, tracking more than one site. Not now. ## Repo https://github.com/bbelderbos/checkpulse ## User journey 1. Owner adds one <script> tag to their site [MVP] 2. Visitor's browser pings the ingest endpoint [MVP] 3. Server anonymizes and stores the event in SQLite [MVP] 4. Owner reads the dashboard behind basic auth [MVP] 5. Owner filters by period (today / 7d / 30d) 6. Track custom events (clicks, signups) ## MVP boundary Build now: Owner adds one <script> tag to their site; Visitor's browser pings the ingest endpoint; Server anonymizes and stores the event in SQLite; Owner reads the dashboard behind basic auth Defer: Owner filters by period (today / 7d / 30d); Track custom events (clicks, signups) ## Priorities ### Owner adds one <script> tag to their site - Serve a ~700-byte /script.js with no cookies - Auto-handle SPA route changes ### Visitor's browser pings the ingest endpoint - POST /api/event that accepts path + referrer ← start here - Fire-and-forget, never block the page ### Server anonymizes and stores the event in SQLite - Hash IP + UA + day into a visitor id, keep no raw IPs - One events table, one index on (site, time) ### Owner reads the dashboard behind basic auth - Views, unique visitors, top pages, top referrers - Browser + device split from the user agent ## Constraints - Single user (no auth, no permissions, no multi-tenancy) - No realtime / offline is fine (no websockets, no sync layer) ## Storage - SQLite — one file, real queries, still no server ## Dependencies - axum (web server) - sqlx (SQLite) - askama (dashboard templates) - sha2 (visitor hashing) ## Map ```mermaid mindmap root((Privacy-first web analytics in a single self-hosted binary)) MVP now Owner adds one script tag to their site Serve a ~700-byte /script.js with no cookies Auto-handle SPA route changes Visitor's browser pings the ingest endpoint POST /api/event that accepts path + referrer * Fire-and-forget, never block the page Server anonymizes and stores the event in SQLite Hash IP + UA + day into a visitor id, keep no raw IPs One events table, one index on site, time Owner reads the dashboard behind basic auth Views, unique visitors, top pages, top referrers Browser + device split from the user agent Defer Owner filters by period today / 7d / 30d Track custom events clicks, signups Constraints Single user No realtime / offline is fine Storage SQLite Dependencies axum web server sqlx SQLite askama dashboard templates sha2 visitor hashing ``` ## First thing to build POST /api/event that accepts path + referrer --- Scoped with scopefirst. The simplest thing that works is often the real version.

Step 1 · The spec

What are you building?

Write the spec before the code. One line, then the problem, then what you are deliberately leaving out.

In one line, what is it? What problem does it solve? What is explicitly out of scope? Repo link, if you've started one (optional)

Naming what you won't build is half the design.

Step 2 · User journey

What happens, in order?

Don't start with features. Start with the user. What happens when they first show up? What do they need next? What closes the loop? Aim for 4 to 6 stages.

Press Enter to add. Features slot into these stages later.

Step 3 · The MVP boundary

Which stages make it real?

The first two or three stages are almost always your MVP. Tap the stages a user needs before anything else makes sense. Everything else won't disappear, it just stops demanding your attention now.

The moment you draw this line, you are not building everything.

Step 4 · Break it down

What's inside each MVP stage?

Drill into each MVP stage and list its sub-features, until each one is something you could write an issue and PR for. Star the one or two you would tackle first.

Only your MVP stages need this now. The rest can wait.

Step 5 · Constraints that set you free

Each yes removes a class of problems.

Good architecture is often less about what you build and more about what you decide not to build.

Step 6 · Boring storage, few dependencies

Pick the most boring storage that works.

For small data you rarely need a database. Plain text is readable, editable, greppable, and backed up with standard tools.

Dependencies (every library is code you maintain forever)

0 dependencies. Two is better than twenty.

Step 7 · Your brief

Here's what's worth building first.

This is your design artifact. Hand it to your AI to guide the build, or to someone who has shipped this before.