Requirements start as a voice note

This series follows one feature on my own site, from a voice note to production, with AI agents doing most of the building. The feature I picked sounds simple. The AI assistant on my site should learn from the articles I write. This part covers the first hour, before any code was written.

Step 1: I talk before I type

Every feature I build starts as a voice note. I dictate with Wispr Flow straight into Claude Code: what I want, who it is for, what worries me. There is no ticket, but the shape is familiar, close to a user story. What we learned about writing requirements for people works almost unchanged when the reader is a machine.

Then I read the transcript and fix what the dictation got wrong. Speech is fast, but it makes small mistakes. They are easy to catch, and they remind me that the first artifact of the process is already a machine's version of what I meant.

That voice note is this project's first business requirement. The part that became the feature:

The feature is a change to the AI assistant on my site, so that it learns to answer questions based on the articles I write and expands its knowledge and skills.

One sentence and no acceptance criteria. That is a normal first input, and the process has to cope with it.

The brain dump does not have to be mine. It can come from a session with a business user, from a workshop or from a meeting recording, and it can go back and forth with the end user as often as needed. Business requirements still exist; they just arrive in a different form. Even working alone, I cannot keep them in my head. Everything has to end up written down somewhere the AI can read it: a backed-up folder, GitHub issues, a decision log. A team needs more than that: a shared place for requirements, a sign-off and a record of who decided what.

Watch out: unsigned requirements. Requirements now often start as someone talking, and nobody signs them off. Ask for a sign-off; it takes minutes. Keep what each person gave you in whatever form it came: user stories, acceptance criteria, signed documents, recordings, screenshots. Without that, you cannot check later whether the agent built what was asked or only what it understood.

Watch out: the wrong weight of documentation. Documentation can fail in three ways. There is none, there is too little, or there is so much of it, produced by agents on autopilot, that nobody reads it, including the people who "wrote" it. The third one is new: AI slop. As always in delivery, match the documents to what you are actually building.

Step 2: the agent interviews me

Next I run a "grill me" skill. The agent asks me about one decision at a time. Each question comes as a small window with two to four options and the agent's recommendation first. I click one, or I type or dictate my own answer.

The skill comes from Matt Pocock's open-source collection: see grill-me on GitHub and his guide to the grilling skills.

In this run the questions were about what to build and how it reaches visitors. Should the articles section be built now or later? How do we demo the assistant? Who approves what goes live? Where should the Dispatcher's questions land? Most of the time I clicked the recommendation.

My own answers mattered more. Answering a closed question about deployment, I added something nobody had asked for: an admin panel to upload articles, with the section hidden behind a URL flag until it is ready. When another question assumed the assistant was switched off, I asked the agent to check before I picked anything. That is how the first failure below came out.

So the scope grew. I came in with one feature, the assistant learning from my articles, and left the interview with three: an articles section, an admin panel to publish articles, and the assistant learning from them. There was no change request and no impact assessment, only a conversation.

Watch out: scope decided in a click. Requirements are now set in conversation, and whoever writes the options shapes the decision. Clicking the recommendation does not always mean you agree with it; sometimes you just had no time to think. Scope can also grow inside one answer, and nobody sees the cost. Log every question and answer, and treat a new requirement as a change even when it arrives as one sentence. AI helps here too: after each conversation, have the agent update the list of requirements and mark which items refine what was agreed and which are new scope that needs a change request.

Failure 1: the agent believed the documentation

Halfway through the interview the agent stated that the site assistant was switched off for visitors and asked how to demo a feature nobody could see. I asked it to check instead of choosing an option. It was wrong: the assistant had been live for eleven days. The project's instructions for agents still said it was off, and a check on the production server settled it.

The stale documents were fixed in a separate session so the interview could go on. Part 3 explains how that hand-over works and why it matters for a team.

Watch out: agents trust stale documents. An agent treats the documentation it gets as the truth. Stale documentation is an old problem. The difference is that an agent acts on it at once, and there is no hallway conversation to catch the mistake. Keep the instructions for agents as current as the code.

If I ran your team

I would start by recording every requirement conversation and its outcome in one place, signed off by the person who owns it. I would also make the agent keep the list of requirements up to date after each session, so new scope shows up as a change and not as a surprise in the demo.

With the scope settled and the facts checked, the work went to the agent that builds. That is Part 2.