← All sessions

Session 2

Guided Flows — Scripted Routes, Live Data

Last session you built a chatbot that's honest: it answers only from sourced fact sheets. Tonight you make it useful. You'll add a guide that asks a few short questions and leads to a real next step: an installer search, a grant page, or your own home's energy certificate, looked up live from the government register.

You design the flow. The agent plays it back to you, breaks it into issues, and builds it. Then you try to knock it off course.

The lesson: the code decides where the conversation goes. The model only works out what someone meant when they typed instead of clicking.

Your folder: energy-qa, the one you built in Session 1.

1 — Set up

Open your energy-qa folder in VS Code and check the Session 1 Q&A still runs (python app.py). If it doesn't, ask the facilitator for the working copy.

Download the seed kit and unzip it straight into energy-qa (so CLAUDE.md lands next to your Session 1 app.py). It adds:

  • CLAUDE.md, the new rulebook (it replaces your Session 1 one and includes all the old rules)
  • guide-spec.md, what to build
  • flow.md, the flowchart: a core plus optional branches you choose from
  • epc-fixtures/ and address-notice.txt, sample certificates and the address copyright notice (don't edit these)
  • .claude/skills/to-issues/, the /to-issues command from Session 4
  • .env.example

On a Mac, Finder hides folders starting with a dot. To check .claude/ arrived, run ls -a in the VS Code terminal.

Open your existing .env and add the two lines from .env.example. Paste in the EPC token the facilitator hands out tonight.

2 — Design your guide

read CLAUDE.md, then play my flow back to me

The agent shows you a quick diagram of the guide and a short menu of optional branches:

  • A. Solar
  • B. "Check my EPC first"
  • C. Next steps from the certificate

Add any you like, or none. Reword any question you'd put differently. Then the agent shows the diagram again with your branches added, plus two short example conversations, word for word. Read them as if you were a resident at a stall. Is that what you'd want to be asked? Say yes only when it is.

3 — Break it into issues

/to-issues @guide-spec.md

Check the slices it proposes:

  • Does it start with the EPC lookup on its own?
  • Is there a terminal walkthrough of the flow before any web page?
  • Are only your chosen branches included?

Approve it, and the issues go into todo.md.

4 — Build it, one issue at a time

build the next issue in todo.md

Repeat. At each HITL checkpoint the agent runs the check itself and shows you the result. You just look and answer:

  • The EPC lookup: it asks for your postcode, shows the homes registered there, and asks which is yours. Then it shows your certificate's recommendations. They should read in plain English, like "Floor insulation (solid floor)", with costs. Bare numbers like "improvement 58" mean the decoding isn't working yet.
  • The flow: it shows you two example walks through your guide. Check they match what you approved in step 2.

5 — Walk your guide

Once it runs in the browser, open the address it prints. Walk every branch you built. Look up your own home, and see what its certificate recommends.

6 — Now try to knock it off course

This is the point of tonight. Try these:

  • At the first question, type "I rent, just give me an installer's phone number."
  • At "Do you own your home, or rent it?", type "what's a heat pump?"
  • Enter tonight's venue postcode (the facilitator will tell you). Is the building listed?
  • Pick "My home isn't listed".
  • After seeing your certificate, click "Ask a question" and ask "what's my EPC rating?"

Good: it asks again, lands on a real option and carries on, or says plainly that it doesn't know. Bug: it skips a step, chats in its own words at a choice step, names an installer, or shows a figure that isn't on a certificate. Tell the agent:

at the <step> step the guide <what it did>. The code must decide the route, and the model can
only return one of the step's option ids or "unclear". Fix that and let me try again.

Things to try once it's working

  • "Add another branch to flow.md, play it back to me, then build it."
  • "Show me which option id classify_reply returned for each thing I typed."
  • "Switch EPC_MODE to fixture: what's different about the two sample certificates?"