How the AI brief works: from your problem in plain words to a spec
· 9 min · ai, brief, agentic-coding, edge
The point every project in the lab starts from. You describe a problem, the AI helps squeeze it into requirements that then become the spec an agent works against.
Before writing a line of code you need to know what you’re building. Obvious to say, almost never true in practice: you start from a half-formed idea and discover it while coding. The wizard on /request is my attempt to move that discovery earlier, and to do it with two heads: mine and the model’s. It isn’t a form to fill in. It’s a guided conversation that ends with a document you then work against.
You start from the problem, not the sector
The first screen asks one thing: what’s the problem, in your own words. No dropdown of categories, no “pick your sector from 40”. You write that you run an outpatient clinic and bookings come in on three different channels, and from there the AI infers the sector on its own. It does it with the analyze action of the edge function: it reads the free text and pulls out the field, the tone, the kind of product. If it gets it wrong it corrects later, but in almost every case it starts framed well, and that changes every question that comes after.
If you don’t feel like typing you can dictate: I use the browser’s speech recognition (Web Speech), so the transcription happens on the device, without the audio passing through me. It’s a convenience I keep because it removes the initial friction: the blank screen is where people give up.
The context questions, one per screen
Once the field is clear, the wizard asks a few context questions: who the users are, what they need to be able to do, what already exists. One question per screen, never a long questionnaire that intimidates. The rhythm is a chat’s, not a form’s. The answers don’t go into a drawer: they become the raw material the AI, in the next step, uses to try to deduce the real requirements.
The requirements phase: the AI proposes, you decide
This is the core. The AI doesn’t ask you to “list the requirements”: asking a client that is the fastest way to get a wrong list. It proposes them: with the propose_requirements action it looks at the problem and the context and drafts a first list of things the system should do. You read and react: this yes, this no, this is nearly right but the payment is end-of-month not on order. Each correction goes back to the model with refine_requirement, which rewords that single requirement and offers it back sharper. You go round like that until the list sounds right.
The point I defend is that the model never closes the door. You can add a requirement it hadn’t thought of, drop one, split one in two. The AI rewords, it doesn’t impose. It’s a loop with the human inside at the point that matters: the decision on what the system must actually do stays yours, the AI does the smart-stenography work around it.
The count is done before the model
Behind it there’s a single edge function, generate-brief, with four actions: analyze, propose_requirements, refine_requirement, generate_brief. Each has its own model slot (the initial analysis can run on a cheap model, the final brief deserves the good one) so I don’t pay for a big model on a small task. And there’s a rule I learned the hard way: the rate limit is counted before calling the model, not after. If you reject a requirement ten times in a row and the AI rewords ten times, those calls count; but a request refused by the limit must not burn budget it never spent. Early on I had it backwards, and an afternoon of empty testing ate my daily cap without producing anything.
The brief: frozen requirements, milestones, timelines
When the list is settled, the generate_brief action compiles the document. The requirements freeze: they stay the ones you approved, verbatim, not a paraphrase the model invents at the end. On top it puts a proposed set of milestones, a phased roadmap and a realistic time estimate, with a note on which part is most uncertain. The brief isn’t a quote and doesn’t pretend to be: it’s an agreement on what we build and in what order.
Why it’s the same framing every project starts from
The reason I care about this step goes beyond /request. It’s exactly how every project in the lab starts, even when the client is me. Before putting an agent to write code, I write the framing: what it has to do, the real constraints, what it must not break. The brief, requirements plus roadmap, is that spec. It’s the document the agent implements against and the one I read the result against: if the behaviour doesn’t add up, the comparison is with the brief, not with what I remembered wanting to do.
It’s this human→AI handoff that makes the rest reliable. An agent left without a spec writes something plausible, and three days later you realise it solved the wrong problem. With a clear brief in front of it, agentic coding stops being a gamble and becomes work with a yardstick. The AI brief isn’t an entry gadget: it’s the first link in the chain I build everything with.
What comes next
What it doesn’t do yet, and I’d like it to. Today the brief comes from words: it doesn’t look at an existing site, a spreadsheet, the screenshot of the software you already use. I’d like to start from real material (“here’s how it is now, here’s what’s wrong”) instead of the description alone. Then there’s memory: every brief starts from scratch, but many problems rhyme, and a library of recurring requirements (login, payments, roles) could shorten the boring part. And finally the link I wire by hand today: from an approved requirement to the tests that verify it. The day every requirement in the brief is born with its own check, the “does the code do what we said?” comparison is done by the machine. None of these come with a date; they’re the directions I’m looking in.