Why a Normal Spec Isn't Enough When AI Builds the Thing

A build-in-public lesson from Household OS, and what it means for the AI policy sitting in your school's shared drive

It started with a reel. Kerrie sent me one of those Instagram finance videos over the weekend, the kind about couples who have no idea where their money actually goes, with a caption that amounted to this is us. She was not wrong. We live in Dubai, most of our spending happens by card tap, and the only record is a stream of bank SMS alerts that neither of us ever reads.

Normally that thought dies on the sofa. But OpenAI had just shipped GPT-5.6 with its new Work feature, an agent built to run multi-hour projects rather than answer single prompts, and I had been looking for an excuse to test it properly. Not on a toy. On something with real stakes, real data, and a real second user who would notice if it was rubbish.

So the reel became a project: Household OS, a private spending tracker for Kerrie and me. It is still being built, but the bar is set: capture a spend in under five seconds. Sync between our two phones in under one. Pull transactions straight from those bank SMS alerts. And the experiment underneath it: hand as much of the process as possible to AI. GPT-5.6 comes as a family of three models, Sol, Terra and Luna, and I used all of them through Work. Sol, the flagship, did the heavy lifting: planning, research, and writing and reviewing the specifications. Terra and Luna picked up the lighter jobs along the way. Codex wrote the actual code.

I have spent years writing documents that tell people what to build and why. This project needed something different, and the difference is worth sharing, because it is not really a software lesson. It is a lesson about what happens the moment you hand a document to something that cannot ask you a clarifying question.

An AI does not fill a gap in your instructions with judgement. It fills the gap with a guess. The guess sounds confident, and it is often wrong.

That one idea changed how I wrote everything after it, and it is the same idea sitting underneath every AI policy, curriculum content file, and marking rubric a school hands to a machine.

A normal spec answers what and why. AI needs more than that

A normal product document tells you what you are building and why it matters. That is enough for a human engineer, because a person fills in the gaps with their own judgement. Tell a competent developer "users should only see their own household's data" and they already know how to make that safe. They have built that pattern before. They ask you a question if they are not sure.

Sol does not do that, and neither does Codex. Give either one the same sentence and it will produce something that looks entirely correct and quietly gets the access rules wrong, because the sentence never told it which rules to apply. It does not flag its uncertainty. It just picks something and moves on, confidently.

So every vague sentence in a document you hand to AI becomes a decision you have made without noticing you made it.

Build the document as a stack, not one page

Here is the part I did not expect: this was not my idea. I went in planning to write one good PRD, the way I would for a human team. Partway through planning, Sol stopped and redirected the whole approach:

"I don't think this is one PRD anymore. I think we're building a Product Design Specification, which contains every document required to build V1. Think of it as a miniature version of what Apple would hand to an engineering organisation."

A few exchanges later it went further, declaring that we were "no longer writing documents" but "executable specifications", and eventually announced, with more ceremony than I expected from a machine:

"We're now leaving Chat mode and entering Specification mode... A project of this size deserves a proper specification suite with consistent formatting, versioning, identifiers, traceability, and document cross-links."

The AI, in other words, told me that the document I was about to write for it would not be enough for it. It was right, and the reason is the one this whole piece turns on. The mistake is trying to cram everything into a single document. It ends up too vague to build from and too dense to actually read. In one giant document, a vague sentence hides. In a small, bounded spec with numbered requirements, a gap is obvious, and it can be removed before any code is written.

On Household OS, the documents sit in layers, and each layer has its own job and its own reader. PRODUCT.md, ARCHITECTURE.md and AGENTS.md set out what we believe, who it is for, and the rules we will not break, things like "never store a bank password" and "the household owns the data, not the user." Above the code sits the implementation plan, the phased build order. Below it sit six engineering specs, each one owning a single slice: the database contract, the offline sync protocol, the SMS security and ingestion protocol, the backend contract, the operations guide, the AI evaluation framework. One more document tracks exactly where the build is right now, so a new Codex session picks up from the repository, never from a remembered conversation. Its one rule says it plainly: "Resume from repository state, never chat history."

None of those documents talk about database columns in the vision layer, and none of them talk about brand feeling in the database layer. Keeping the layers separate made every one of them easier for Sol to write and far easier for me to check. It also contained the damage when something needed fixing: the database contract went through five patch cycles on its own while every other document sat untouched. Nobody can meaningfully review a five-hundred-page monolith, but a reviewer, human or AI, can properly attack one focused document.

The biggest shift: conceptual versus implementation grade

This is the part that made the real difference. There is a large gap between a requirement that reads well and one an AI can build without guessing.

Take the same requirement, written both ways.

Conceptual, the way most documents would put it:

"Financial data belongs to the household, not the user. Users only see their own household's data."

Implementation grade, the version that could actually be built and checked:

Every spending record carries a household ID that must always be filled in. Row-level access is locked down so a member can only read records for a household they actively belong to. The rule enforcing that had to be rewritten once we caught it quietly calling itself in a loop, a real bug that only showed up because we tested it properly. Permissions are set separately for logged-out users, logged-in users, and the server itself. There is a required test called "a user cannot read another household's data," and another called "a user cannot edit fields only the server should control."

Same requirement. One is a sentence a person nods along to. The other is buildable, and it is what actually got built, backed by a database test suite currently sitting at 941 passing tests out of 941. The lesson is simple: the AI will not ask you to clarify. It will decide for you, and you will not find out which decision it made until the thing is already built.

The test for a document that is actually ready

There is a straightforward way to know if a document is ready to hand to AI. Ask whether two different teams, given only this document, would build essentially the same thing.

If yes, it is ready. If there is a fork in the road the document does not settle, the AI will pick one for you.

This is the exact test the project's own AI-ready spec template asks you to apply before you consider a document done. The template itself came out of Sol's "Specification mode" pivot: every document gets the same shape, with stable IDs and requirements numbered so each one can be traced to a test. The condensed version is a skeleton worth keeping, whatever you are writing:

Metadata: an ID, a version, a status, what it depends on. Purpose: one job, one document. If it needs "and", consider splitting it. Numbered requirements: so each one can be traced to a test later. Detail: for anything risky, the exact behaviour, not the idea. Edge cases: written out on purpose, because AI handles the happy path and invents the rest. Acceptance criteria: a clear, checkable list of what "done" means. Open questions: uncertainty flagged in the open, not hidden. Decisions: a short record of why each big choice was made, so nobody re-argues it later.

Treat the document like code, not like a memo

A normal document gets written once and slowly rots while reality moves on around it. These do not get to rot. Each engineering spec carries a version number in its filename (the database contract is on v1.5, the backend contract on v1.2), and a status that moves from draft to review to approved to frozen. The repository's own rule is blunt about what happens after that: "Frozen specs under docs/ are binding and must not be edited" unless the task is explicitly to revise the spec, and any change goes through a proper decision record rather than a quiet edit.

This matters because the AI builds from the document in front of it. If the document keeps shifting underneath the build, Codex is aiming at a target that keeps moving, and every gate we run before calling something done, formatting, linting, strict type checking, the full test suite, contract verification, a production build, exists to catch the moment a document and the code drift apart.

Do not over-document either

Here is the honest part. At one point Sol, left to plan, wanted to write well over a hundred specifications running to hundreds of pages. It was being thorough because thorough is what it does when nobody sets a boundary. Most of that was too much, too early, and it would have slowed the build down for no real gain.

Detail is a cost. Spend it where a wrong guess is expensive. On this project that meant financial data, device sync, and the security boundary between the app and the server got the deep, buildable treatment, right down to a stated target of under 0.5% duplicate transactions and 99%+ successful imports from bank SMS alerts. The lighter, easily reversible parts of the interface stayed simple. You do not need to gold-plate a button.

What this means for a school

Here is why I think this is worth ten minutes of an educator's time rather than just a developer's.

The exact same gap sits inside a school AI policy, a set of curriculum content files handed to an AI tutor, or a marking rubric you expect a colleague to apply consistently. "Use AI responsibly" is a conceptual sentence. It reads well. It is not buildable, and if you ever put it in front of an AI tool, an AI marking assistant, or a chatbot with access to student work, it will not ask you what "responsibly" means. It will decide for you, and it will decide differently every time, because there was never a rule there to follow, only a feeling.

The implementation-grade version names the actual rule: what the tool can and cannot see, what happens when a student pushes it off task, what "done" looks like for a piece of AI-assisted work, and what a teacher checks before it counts. That is the same shift this piece has been describing the whole way through, moved from a household spending app to a staffroom policy document. I have written about the policy side of this directly in Why the First Page of Your AI Policy Might Be the Only One That Matters, and about what it looks like to hand an AI tutor real, teacher-controlled content rather than a vague brief in Grounding AI Responses in Actual Curriculum. The DEEP AI Literacy Audit's nine fixed dimensions exist for the same reason this household's engineering specs exist in layers: a framework that names the actual requirement outlasts a policy that only names the intention.

The test holds here too. Would two different teachers, given only your policy or your rubric, apply it the same way? If not, you have not written a policy. You have written a preference, and every person and every AI tool reading it will fill the gap differently.

Frequently asked

What did you actually use to build this? OpenAI's GPT-5.6 family through the new ChatGPT Work feature. Sol, the flagship model, handled planning, research, and writing and reviewing the specifications; Terra and Luna, the lighter and faster tiers, handled smaller jobs; Codex wrote the code. The tools will keep changing. The lesson about how you write for them will not.

Is this only relevant if I am building software? No. The core problem, an AI filling an ambiguous instruction with a confident guess rather than asking a question, shows up anywhere a school hands AI a document to act on: a policy, a curriculum content file, a rubric, a set of instructions for an AI marking tool. The fix is the same in every case: name the actual rule, do not just describe the intention.

What is the quickest way to check if my school's AI policy has this problem? Ask whether two different members of staff, given only the policy document, would make the same call in the same situation. If the answer is genuinely yes, the policy is doing its job. If there is an obvious fork in the road the document does not settle, that is exactly where an AI tool, or a member of staff, will end up guessing.

Does writing this way mean producing far more documentation? No, and that is the part worth being disciplined about. Spend the detail where a wrong guess is expensive, safeguarding, data, assessment integrity, and keep everything else short. More pages is not the goal. Fewer gaps where it actually matters is.

What is Household OS? A private, shared spending tracker I am building for my wife and me, born from a reel she sent me and built as a real-world test of GPT-5.6 and ChatGPT Work. This post is one piece in a build-in-public series about what that process has actually taught me, and I will keep pulling out the parts that are genuinely useful for educators as the build continues.

This is one piece in a build-in-public series following Household OS. If this was useful, share it with a colleague who is drafting an AI policy, a rubric, or curriculum content of their own. The more of us who get precise about what we actually mean, the less guessing the machines will have to do on our behalf.