Requirements and Roadmapping

Writing down what you're building sounds like bureaucracy until the third time you rebuild the same screen because you changed your mind halfway and forgot why. Requirements are not paperwork; they're a way of thinking before you type.

The concept

There are three separate documents doing three different jobs, and conflating them is the usual mistake:

Solo founders often keep all three in their head, which works until context is lost, a two-week gap, a new collaborator, a fresh AI session, or simply Monday morning.

The lightweight spec

You do not need a 20-page PRD. For most features one page is right:

FEATURE: [name]

PROBLEM      Who has it, how often, what it costs them today.
             (If you can't write this, stop — you don't have a feature,
              you have a solution looking for a problem.)

OUTCOME      What's true when this works. Measurable if possible.

USER STORY   As a [persona], I want to [action], so that [outcome].

SCOPE        In:  bullet list
             Out: bullet list ← the more important half

EDGE CASES   Empty · error · offline · slow · first-run · returning ·
             maximum · concurrent · permission denied

DEPENDENCIES What must exist first? What breaks if this changes?

DONE WHEN    Testable conditions, not vibes.

The "Out" list is the load-bearing part. It's the difference between a feature that ships and a feature that grows.

Edge cases are 30% of the work and 90% of the surprises

The checklist above is worth internalising, because these are where estimates die:

• Empty, no data yet. First-run is the most-seen screen in your product and usually the least designed.
• Error, network fails, server 500s, permission refused. What does the user see and what can they do?
• Offline, especially mobile. (Chapter 19.)
• Slow, 3G, cold start, large data. Skeletons over spinners.
• First-run vs returning, completely different needs.
• Maximum, 10,000 items, a 5,000-character name, a 400 MB upload.
• Permission denied, camera, notifications, location refused. Never dead-end.

Prioritisation, honestly

Frameworks are decision aids, not decision makers.

RICE, (Reach × Impact × Confidence) ÷ Effort. Good when comparing many similar-sized items. Its weakness is false precision; the numbers feel objective and aren't.

MoSCoW, Must / Should / Could / Won't. Good for a single release. Its value is entirely in the Won't column.

Value vs effort 2×2, crude, fast, usually enough.

The honest solo-founder version: "What is the single biggest risk or blocker right now?" Do that. Repeat. Most early roadmapping is over-engineering a queue of length one.

Roadmaps: horizons, not dates

Dated roadmaps beyond ~6 weeks are fiction and everyone knows it. Use horizons:

 NOW (this cycle)      committed, in progress, dated
 NEXT (1-2 cycles)     likely, ordered, undated
 LATER (someday)       directional, unordered
 NOT DOING             explicit, with reasons  ← the most useful column

That last column prevents the same suggestion arriving every month.

The status file: the highest-ROI document you'll keep

One file, in the repo, curated. It answers: what is this, what's done, what's next, what's explicitly deferred and why, what's broken, where things live.

Its real job is surviving context loss, yours after a break, a collaborator's on day one, or an AI assistant's between sessions. Without it, every restart re-derives the project from the code: slow, expensive, error-prone.

📐 Update it at milestones, not continuously. A file that updates on every change becomes a changelog, and a changelog is not a status. The value is in the curation, someone deciding what's still true and what matters now.

📐 Best practice

One page per feature. Problem first, solution second. If the problem section is hard to write, the feature isn't ready.

Write the "Out of scope" list explicitly. It's what makes the spec hold.

Walk the edge-case checklist every time. It takes five minutes and it's where the surprises live.

Define "done" as testable conditions, not "it works."

Keep a NOT DOING list with reasons. Reasons matter, circumstances change and you want to know whether the reason still holds.

Maintain one curated status file, including a "decisions locked" section so settled questions stop being re-litigated.

Write decisions down with dates and reasoning. A lightweight decision record, what we chose, what we rejected, why, when, costs two minutes and saves an hour of re-arguing.

Re-read your strategy documents at milestones. Products drift; nothing else catches it (Chapter 06).

💀 Common mistakes

No written scope at all. Every conversation re-opens settled questions.

A 20-page PRD for a two-day feature. Process theatre. Match the document to the size of the bet.

Solution-first specs. "Build a dashboard with these six widgets", with no statement of the problem, you can't tell if it worked.

Ignoring edge cases until they appear in production.

Dated roadmaps past six weeks. They will be wrong and someone will hold you to them.

A roadmap with no "not doing" column. The same idea returns forever.

Status file as changelog. Auto-appending every change makes it unreadable, so nobody reads it, so it stops being a status.

Prioritising by whoever asked most recently.

Confusing a roadmap with a commitment. Internally it's a plan; externally it's a promise. Be careful which one you publish.

The professional workflow

 1. CAPTURE — one inbox for every idea/request. No filtering.

 2. TRIAGE weekly:
      now · next · later · not doing (with reason)

 3. SPEC the "now" items — one page each
      problem → outcome → story → in/out → edges → done-when

 4. ESTIMATE in t-shirt sizes (S/M/L). Hours are false precision.

 5. BUILD one vertical slice at a time (Chapter 07)

 6. VERIFY against "done when" — not against vibes (Chapter 28)

 7. UPDATE THE STATUS FILE at the milestone, curated

 8. RECORD THE DECISION if you rejected an approach:
      what · why · date

Tools, websites & costs

For a solo founder: markdown in the repo plus GitHub Issues is genuinely enough. Versioned, diffable, travels with the code, no subscription. Add tooling when you add people.

Alternatives & trade-offs

Shape Up (Basecamp), fixed six-week appetite, variable scope, "shaped" work rather than specs. Excellent for small teams who over-plan. Requires discipline to stop at the appetite.

Kanban / continuous flow, no sprints, just a prioritised queue with WIP limits. Often the best fit for solo founders and small teams; sprint ceremonies are overhead you don't need.

Scrum, heavy for teams under ~5. The ceremonies exist to coordinate people you don't have yet.

Outcome-based roadmaps, commit to outcomes ("reduce time-to-first-value by half") rather than features. Better strategy, harder to plan against.

No process at all, genuinely fine for the first few weeks. Introduce structure at the first symptom (forgetting decisions, rebuilding things, losing context), not before.

Trade-off: every process costs time now to save time later. Solo, the break-even is much further out than most advice assumes. Start light.

Checklist

• Every "now" feature has a one-page spec
• Each spec starts with the problem, not the solution
• Each has an explicit out-of-scope list
• I walked the edge-case checklist (empty, error, offline, slow, first-run, max, permission)
• "Done" is defined as testable conditions
• My roadmap uses horizons, not dates beyond ~6 weeks
• My roadmap has a NOT DOING column with reasons
• I keep one curated status file with a decisions-locked section
• I record rejected approaches with dates and reasoning
• I re-read strategy docs at milestones
• My process is as light as my team size allows

📓 Case Study: one file that carried a whole project

Project: SOLIS.

The artifact: a single file, AppStatus.md, created on day 12 in response to a specific, mundane problem:

"can you summarise all of what we have done in this chat i want to start a new session, from the chat starting, all the goals we have achieved and a summary of our app, and next goals in a new project status file"

The trigger was context loss. Sessions ended, context windows filled, days passed. Every restart meant re-deriving the project from the code.

It grew to 624 lines and held: what the product is · everything done chronologically with commit hashes · the launch-readiness checklist · the backlog with dates and reasons · known bugs with root causes · key files annotated · and a "read this first" section for the next session.

From day 12 onward, every working session began with "read AppStatus.md and let's continue." One file read, fully oriented. For a project built across many discontinuous sessions, this was the single highest-ROI file in the repository, more valuable than any individual piece of code.

The update policy was the interesting decision:

Update policy: only when the user explicitly asks (not automatically).

That looks like laziness and isn't. A file that updates on every change becomes a changelog; a changelog is not a status. The value is in the curation, a human deciding what is still true and what now matters. An auto-generated one would have been longer, more accurate, and useless.

What it did well: the backlog entries carried reasons and dates, not just titles, "Art QA, a minority of reassigned images are tonally off. User chose leave as-is," dated. Six weeks later that's the difference between a settled decision and an open question.

⚠️ Deviation 1: no per-feature specs, and edge cases were consistently discovered late.

Features went from a chat message to implementation with no written problem statement, scope boundary, or edge-case pass. The costs were traceable and repetitive:

• Returning-user paths were missed twice, sync uploaded data but never downloaded it (so a reinstalling user saw an empty app), and the auth flow didn't handle "anonymous user whose identity already exists." Both are standard entries on the edge-case checklist. Both shipped broken and were found later.
• Animated onboarding screens showed their end-state when re-entered, because re-entry wasn't considered.
• Out-of-order completion broke progress tracking, because "user does things in an unexpected order" wasn't on any list.

None of these are exotic. A five-minute edge-case walk per feature would have caught all of them. The absence of a two-page ritual cost several days of debugging.

⚠️ Deviation 2: findings were recorded in prose, not converted to tracked items.

A security review on day 1 produced eight real findings. They were written into a chat message and never became issues, checklist entries, or status-file lines with owners and dates.

Twenty-four days later, seven of the eight were still open, including a paywall bypassable via a URL parameter. The one that got fixed was fixed by accident, as a side effect of unrelated work.

The lesson is not "do more security reviews." It's that a finding that isn't in a tracked list does not exist. The review produced a document; documents don't fix anything. What was missing was step 8 of the workflow above, and a launch-blocking gate that said "all critical findings closed."

What generalises: the status file was excellent and the specs were absent, and you can see the shape of both in the outcome. The project never lost the thread (thanks to the status file) and repeatedly lost the details (for want of specs).

Lessons

1. Three documents, three jobs. Spec = what and why. Roadmap = order. Status = where we are now.
2. A curated status file is the highest-ROI document a small team keeps. It's insurance against context loss.
3. Curate, don't auto-generate. A changelog is not a status.
4. The out-of-scope list is what makes a spec hold.
5. Walk the edge-case checklist every time. Empty, error, offline, first-run, returning, maximum. Five minutes; it's where surprises live.
6. Returning-user and out-of-order paths are the most commonly missed, they're rare in development and common in reality.
7. Record decisions with dates and reasons. Circumstances change; you need to know whether the reason still holds.
8. A finding not in a tracked list doesn't exist. Convert findings to items in the same session, with a date.
9. Keep process as light as your team size allows, and add it at the first symptom, not before.

Next: Chapter 09: The Core Loop: Designing for Retention →