The Foundation

How to set up a project so it survives being wrong

Two days before launch, I found the line that killed it.

I had built a video app for children under 13. Parents pick the library, kids only watch what's approved. It worked. It was on a device, in review, days from being real.

Then I read one rule in the app store guidelines carefully for the first time, and understood that the entire audience I had built for made the product untenable. Not a bug I could fix. A wall I had built straight into.

So I changed who it was for. From young children to teens and adults with autism and intellectual disabilities. Same product. Different people.

And it survived.

That last part is the whole story. Most solo builders in that position start over, and they start over for a reason that has nothing to do with laziness: they genuinely cannot tell which of their decisions were about the thing and which were about the people they built it for. Once you can't separate those two, every choice you ever made is suspect, and burning it down feels safer than auditing a thousand decisions you no longer remember making.

I could separate them. Not because I have a better memory than anyone else. Because I had written down why I made each one, the day I made it.

AI makes code cheap. Context is what survives. I can regenerate a screen in an afternoon. I cannot regenerate the reasoning behind a decision I made six weeks ago. That reasoning is the only thing that made the pivot a Tuesday instead of a funeral.

Here is what that afternoon actually looked like, and the system that made it possible.

---

The audit

When I changed the audience, I did not open the code. I opened a single file called DECISIONS.md, and I went through it one entry at a time, asking each one the same question:

Does this still hold, for different people?

The locked-down player. The thing that guarantees a viewer can never wander off into recommendations. Still holds. Holds harder, actually, for an audience that needs predictability even more than a child does. Keep.

The entire children's-privacy apparatus. Everything I'd built to comply with laws about kids. Gone. Not modified. Deleted, along with every constraint that came with it. The wall I'd hit simply stopped existing for the new audience.

The visual design. Bright, playful, built for a five-year-old. Actively wrong now. An adult with a disability is not a child, and a product that treats them like one is insulting. Replaced, not tweaked.

The role model. Who can do what. This one needed real rethinking, because an adult who can manage their own library deserves a kind of dignity a child's account never has to consider.

That audit took an afternoon. Without the file, it's weeks of archaeology, and I get a meaningful chunk of it wrong, because I'm reconstructing my own reasoning from memory under deadline pressure. The foundation is what turns "start over" into "re-evaluate."

Every one of those four answers came out of a file I'd written on an ordinary day, when it felt like pure overhead. Here's the system those files belong to.

---

The two files that saved the pivot

There are more, and I'll get to them. But if you build nothing else, build these two. They answer the only two questions that matter when everything changes: what are we trying to do, and why did we do it that way.

VISION.md. What you're building, and for whom. The document everything else gets measured against. Without it you cannot evaluate a single decision, because you have no standard to hold it up to. It holds who this is for in one sentence specific enough to exclude people, the problem in their words rather than your framing, what success actually looks like as an observable outcome, what you will deliberately not build, and the claims you'll never make about the product. When the audience changed, this was the first file I rewrote, and rewriting it is what told me which of the other decisions were now suspect.

DECISIONS.md. Why each choice was made. The most valuable file by a distance, and the one you just watched save an entire product. One entry per real decision: the date, what you chose, the full reasoning including what you rejected and why, what the choice rules out downstream, and what would make you revisit it.

There's a test for whether an entry is actually finished: does it survive someone asking "why?"

"We use a locked-down player" is documentation. "We use a locked-down player because the core promise is that a viewer can never wander into recommendations, and that is the product, not a feature" is a decision. Only the second one is any use to you a month later, when you're standing in the wreckage asking which pieces are load-bearing.

---

The rest, and the day each one earns its place

You don't build these on day one. You add each one the first time you feel its specific absence. Build them all up front and it becomes homework, and you quietly stop.

RULES.md (name it CLAUDE.md or AGENTS.md so the agent reads it automatically). The guard-rail file. Without it, every session starts cold and you retype the same constraints into every prompt until the day you forget one. It holds what the product is, which files to read first and which are dead, the hard rules that must never be broken, and the standard for what counts as proof. The rules that stick are the ones with the incident attached: "be careful with data" gets rationalized away, but "a real profile was destroyed this way once, do not repeat it" does not. You'll add this file the first time an agent does something you never told it not to.

VALIDATION.md. The proof gate. It holds the specific question you're testing, the decision rule written before you have any data, and the date you wrote that rule, so it's provably before the results came in. Why the date matters: I know I'd move the goalposts. Everyone does. A rule written before the evidence is one you can't quietly bend afterward. You'll add this the first time you catch yourself hoping for a result.

ARCHITECTURE.md. The technical map. Every external system and the one job it does, how data moves between them, and every fact tagged verified, intended, or unverified with the date it was last checked. Why the tags: mine once listed a database detail that had been true a month earlier and quietly wasn't anymore. "Verified six weeks ago" tells you exactly how much weight to put on it. You'll add this the first time you can't remember how two systems connect.

DESIGN_SYSTEM.md. The design language. Tokens for color, type, spacing, motion; the prohibitions with their reasons ("never pure black, it causes glare and visual fatigue"); and which source wins when the document and the code disagree. You'll add this the first time your screens stop matching each other.

DESIGN.md. The build spec. Screen by screen: what it shows, what it does, and what it must never do. The invariants stated as behavior, not code: the things that can never regress.

BACKLOG.md. The live queue. What's next in priority order, plus the findings you noticed but didn't fix, written with enough context to act on months later. Add this one early, not because it saves you, but because it's the file you touch daily, and daily use is what keeps the whole habit alive.

CHANGELOG.md. What actually shipped, and when. Kept separate from the backlog on purpose. One is intent, the other is record.

ACCOUNTS.md. Where things live, not what they are. Which service, which identity, what it's for, and where the real credential lives (a password manager, a secret store). It holds no passwords, keys, or tokens, because anything in a repository is in its history forever, and any agent you run inherits access to all of it.

---

The dead file you keep on purpose

One of my files is wrong. It's a pre-pivot overview, and almost every fact in it is now false.

I did not delete it. I put a line at the top saying it's dead and must not be trusted, and I noted that in the other files too.

Deleting is cleaner and worse. Old documents get quoted from memory, resurface in someone's downloads, or get pulled up by an AI that doesn't know they're stale. Stale documentation is more dangerous than none, because it carries the authority of having been written down. A file marked dead is defused. A file deleted is a landmine you forgot you buried.

---

The uncomfortable part

All of this only works if you write things down while they're boring. Before you're stuck, before it's urgent, before you have a shred of evidence you'll ever need them.

Every entry felt like overhead the day I wrote it. Every single one. The value didn't arrive gradually. It arrived all at once, weeks later, on the worst day of the project, in the form of an afternoon that should have been a month.

That's the deal, and it's worth being honest about: the foundation is built on the good days and spent on the bad ones. You will never feel it paying off in the moment you're building it. You'll only feel it the day the wall shows up.

Start with two files. VISION and DECISIONS. Add the rest the first time each one's absence costs you something.

Then when your own wall arrives, and it will, you get to re-read your reasoning instead of reconstructing it, and the question changes from do I start over to which of these still holds.

---

I am Aneil Razvi, a product design and AI experience leader. Cubby, my personal project, is a caregiver-curated video app for teens and adults with autism and intellectual disabilities.

Available for fractional design leadership and advisory work.

If you are building something and you hit a wall, I would like to hear which one.