Plan your reading list before you build it

By the end of this part your project will have a file called docs/flows.md: a one-page plan, in your own words, of what someone does with your reading list and what they see after each action, with a rough sketch of each screen. Your agent builds from this file in Part 6.

You have a running starting page, and an agent that knows who you are from Part 2. Nothing gets built here. You’ll write four short lists of steps yourself, then bring your agent in to review them.

1. Write your first flow

Start with adding a book. In a note or on paper, write the steps from the moment someone decides to add a book to the moment they can see it in their list. Write what the person does and what they see, not how the app works inside.

Yours might read:

I choose Add a book. A form opens.
I type a title. I can also add an author, a note and a reading status.
I choose Add to library. The form closes and my book appears in the list.

What you’ve written is a user flow: the steps a person takes to get one thing done, together with what the app shows them along the way.

Even three steps raise questions. Which details are required? The project’s brief, docs/brief.md, says only the title is. What status does a new book start with? “Want to read” is a sensible choice, since most books are added before they are read. These are your decisions. If you leave them unmade, your agent makes them for you when it builds, and you find out one surprise at a time.

2. Write the other three

Your reading list has four main flows.

The four main flows. Each one starts from the list and returns to it, so the list is the screen people see most.

Write View, Edit and Remove in the same way. For View, say what the list shows for each book, and how you’d find one book among fifty. For Edit, say how you’d correct a typo or mark a book as finished. The whole plan fits on one page.

3. Decide what happens after a mistake

Your four flows describe everything going well. A good part of how an app feels comes from the moments that don’t, so ask of each flow what could go wrong, and write down what the person should see.

They save the form with no title. The form should stay open and say that a title is needed. No blank book is added.
They remove the wrong book. An “Are you sure?” message every time soon becomes a button people press without reading. The brief takes a friendlier approach: the book goes at once, and an Undo option brings the most recent one back with all its details.
A search matches nothing. The list should say so, because an empty screen looks like lost data.
They open the app for the first time. An empty list should say how to add the first book.
A change can’t be saved. Your agent will ask about this one. You’ll learn where the app keeps its books in Part 5. For now a good answer is: say plainly that it didn’t work, keep what I typed, and let me try again.

You don’t need to find every case. The ones you write down now become your first tests, at the start of Part 6, before your agent builds anything they describe.

4. Sketch the three screens

Now draw each screen as labelled boxes: what is on it and roughly where, with no colours and no artwork. Pen and paper is enough.

Your app needs three. Two are the same page in different conditions, which is easy to forget until someone opens the app for the first time and finds nothing there.

Wireframes this rough are enough. They say what each screen must contain and roughly where, so you can spot a missing button before anything is built, and nothing here decides a colour or a typeface.

A sketch like this is called a wireframe. Because it says nothing about how a screen looks, you can settle what each screen contains without being distracted by its colours.

Walk through your flows with a finger on each sketch. To add a book, is there a button to press? After removing one, where does Undo appear? Where does the search field go when there is nothing to search? If a step in a flow has nowhere to happen on a screen, something is missing from one of them. This takes a minute and regularly finds a forgotten button.

Not in this part: colours, typefaces, the mascot and the exact words the app uses. You’ll decide all of those in Part 4. Here, write the behaviour: “the form stays open and says which field needs fixing” is enough.

5. Agree the plan with your agent

Now your agent reviews your plan. The prompt below asks it to compare your flows with the brief, to ask you what should happen after each mistake, and then to save what you agree in docs/flows.md, with your three wireframes redrawn there as boxes made of ordinary characters. The prompt names one piece of work, docs/epics/02-plan.md, and it says what not to touch, so the agent helps you plan and builds nothing.

Start a new conversation in your project; your agent already knows who you are. Copy the prompt, replace the bracketed last lines with your own notes, then send it:

Review my plan

Read docs/brief.md and docs/epics/02-plan.md, and follow that epic. I have drafted the main user flows for this app and will paste them below. Compare them with the brief: tell me what the brief requires that I missed, and what I included that the brief leaves out. Ask me what should happen when something goes wrong in each flow, wherever I have not said. If I want something the brief leaves out, note it under "Later ideas" in docs/flows.md and keep it out of the plan. Do not write or change any application code, and do not choose colours, fonts or a mascot: that is the next epic. When we agree, save the flows to docs/flows.md in plain language, and add a simple labelled-box wireframe there for each screen, based on what I say about my sketches: the list with books, the list with nothing in it, and the add and edit form. Then show me the file and record the outcome in docs/progress.md.

My flows:
[paste your four flows here, with what should happen after each mistake]

My screens:
[say what is on each of your three sketches, from top to bottom]

Paste this into your project conversation.

Your agent will probably point out things from the brief that you left out, such as search, filtering by reading status, or the example books a new visitor can choose to load. Decide whether each one belongs in your flows.

You’ll think of things the brief doesn’t include, such as book covers. Have them noted under Later ideas and leave them out of the plan; you’ll come back to that list in Part 10, where you pick one and build it with prompts of your own. Keeping the first version small is what makes it finishable.

When the agent has written docs/flows.md, open it in your agent’s file view. It is ordinary text. If a step doesn’t say what you meant, say so and have it changed. A later conversation won’t see this one, but it will read this file before it builds anything, so the file’s wording matters more than anything you said along the way.

If the agent started building, or picked colours, tell it: “Stop. This epic is planning only. Undo every change outside docs/flows.md and docs/progress.md.” If the file has no wireframes, ask: “Add a labelled-box wireframe to docs/flows.md for each of the three screens.”

You now have a plan that outlasts the conversation, and something to check every later result against. Next, in Part 4, you’ll decide how your reading list looks and what it says.

FAQ

Can I look at the finished example first?

Yes. Trying the finished app is a quick way to see one set of answers. Write your own flows before or after, as you prefer; yours may differ, and what matters is that you chose them.

What if I change my mind while building?

Change the plan. Ask the agent to update docs/flows.md first, then build the change. The file is only useful while it matches what you want.

Series contents

Plan your reading list.