Section 01
How to use this guide
This project comes with two documents for your student. Understanding the difference between them is the foundation of your role as facilitator.
| Document | Purpose |
|---|---|
| Answer Key (PRD) | The complete, working set of prompts. You use this privately before the session to build the app yourself. It is not shared with your student. |
| Student Workbook | Your student's workbook. It describes what each stage must achieve and what ingredients a good prompt must cover — but never writes the prompt for them. |
📌 The one rule that makes this work
Do not share the Answer Key with your student.
Its purpose is to give you confidence and context as a facilitator — not to be copied.
The student's learning happens in the gap between what the scaffold asks for and the answer they construct themselves.
This guide covers three things:
- How to prepare before the session using the Answer Key
- How to facilitate the session as your student works through the Student Workbook
- What to do when things go wrong — and why those moments are the most valuable ones
Section 02
What your student will build
By the end of this project, your student will have a working browser-based IoT dashboard that:
- Reads live distance readings from a TokyMaker sensor via Adafruit IO
- Displays a color-coded arc gauge and a live history chart
- Triggers a warning banner when the sensor value crosses a threshold they chose and justified
- Runs in any browser on any device — no installation needed
More importantly, they will have practiced:
| Skill | What it looks like in this project |
|---|---|
| Translating ideas into precise language | Writing prompts specific enough to produce the result they actually imagined |
| Diagnosing rather than guessing | Working out why Claude's output was unexpected before sending another prompt |
| Justified design decisions | Choosing an alert threshold and explaining the real-world reason for it |
| Security thinking | Understanding why an API key must never appear in shared code or documents |
| Iterative improvement | Building in stages and refining at each step rather than trying to get everything right first time |
Section 03
Before the session: your preparation
Your most important work happens before the student session begins. Set aside 30–45 minutes to complete the following steps.
1
Build the light sensor project
- → Follow the hardware build instructions for the LightWatcher project.
2
Create your Adafruit IO account and sensor feed
- → Go to io.adafruit.com and create a free account if you don't already have one.
- → Once logged in, create a new Feed. Name it exactly: test.light
- → From your account dashboard, copy your Username and your AIO Key — you will need these to test your app.
- → Keep these credentials private. You will enter them through the Settings panel inside the app, never in any document or code.
3
Build the app yourself using the Answer Key
- → Open the Answer Key document (the PRD) privately — not with your student present.
- → Go to claude.ai (Free account) and start a fresh conversation.
- → Work through each numbered prompt in the Answer Key in order, pasting one at a time into Claude.
- → After each step, download or copy the generated HTML file and keep the most recent version.
- → By the final step you will have a complete, working dashboard. Open it in your browser and confirm it loads.
- → Click the Settings button and enter your real Adafruit IO credentials. Watch that the gauge responds to live data.
- → Note any steps where Claude's output surprised you — those are the moments your student will also encounter.
💡 Why build it yourself first?
When you have completed the project yourself, three things happen:
- You can answer your student's questions from experience, not guesswork.
- You know exactly where Claude's output will surprise them — and you can prepare a question rather than an explanation.
- You model the most important lesson of the whole project: adults learn new things too.
Estimate 30–45 minutes for your first run-through. It becomes much faster each time.
4
Read the Student Workbook before the session
- → Open your student's workbook and read it end to end.
- → Read the three Design Decision questions in Section 2. Think through how you would answer them for this project.
- → Read each of the five Stage cards. Notice they describe a goal and list prompt ingredients — but never give the actual prompt.
- → Read the 'Watch For' warning on each Stage card — these flag the most common places students go wrong.
- → Read the three reflection questions in the 'After Claude responds' box on each Stage — these are what your student must answer before moving to the next stage.
- → Familiarise yourself with the Submission Checklist (Section 7) and the Assessment Criteria (Section 8) so you can share them at the start of the session.
5
Set your facilitation intention
- → Your job during the session is to ask questions, not to write prompts or fix code.
- → When Claude produces something unexpected: ask 'What do you think happened?' before offering any explanation.
- → When your student is stuck: ask 'What does the Stage card say your prompt must cover?' rather than suggesting wording.
- → When they want to move on before something works: ask 'Does the gauge actually show a real number right now?' rather than letting them skip ahead.
- → Resist the urge to fix things quietly. A student who debugs their own broken prompt learns far more than one whose facilitator corrected it in the background.
Section 04
During the session: facilitation flow
Opening (5 minutes)
Before your student opens Claude or the Student Workbook, have them answer the three Design Decision questions in Section 2 of the Brief on paper. The questions are:
- Who is your user? Who will look at this dashboard and what do they need to understand at a glance?
- What does your alert threshold mean in the real world? Not just a number — a real reason.
- What is the single most important thing a user sees first? How will that change when the reading changes?
🎯 Why these questions must come before Claude opens
Students who skip the design decisions tend to write vague prompts.
Vague prompts produce unexpected output.
Unexpected output leads to re-prompting without thinking — which is precisely the habit this project is designed to break.
Five minutes spent here makes the rest of the session noticeably smoother.
Working through the five stages
Each Stage in the Brief follows the same rhythm. Keep to this sequence and resist shortcuts:
| Phase | What happens | Your role |
|---|---|---|
| Student reads the Stage card | They read the goal and the list of things their prompt must cover — alone, before writing anything. | Silent. Let them read without commentary. |
| Student writes their prompt | In the writing box in the Brief — on paper, before Claude is open. | Ask: 'Does this cover every item in the list?' Do not rewrite it for them. |
| Student sends the prompt | They paste it into Claude and read the full output carefully. | Observe. Do not react to the output yourself. |
| Diagnosis before moving on | Student answers the three reflection questions: What is different from my goal? What did Claude interpret differently? What one change would fix it? | Ask the questions if they skip them. Do not answer them for your student. |
| Iterate if needed | Student revises their prompt based on their diagnosis and tries again. | Confirm the core goal is actually met before agreeing to move to the next Stage. |
When Claude produces something unexpected
This will happen in almost every session — and it is the most valuable moment. Use this framework every time, without exception:
The three diagnosis questions
- What exactly is different from what you expected — the logic, the appearance, or both?
- What could Claude have interpreted differently from the way you phrased it?
- What is the one specific change to your description that would fix it?
Only after your student answers all three should they send another prompt.
Stage-by-stage facilitator notes
Common sticking points and the most useful question to ask at each stage:
| Stage | Common sticking point | Question to ask |
|---|---|---|
| Stage 1 — First reading on screen | Student writes a vague opening prompt. Claude produces something much more elaborate — or nothing recognisable at all. | 'Does the Stage card say anything about what to include for error handling? Is that in your prompt?' |
| Stage 2 — Make data visual | Student accepts whatever gauge Claude defaults to without checking it against their design decision. | 'Did Claude match what you said your specific user needs — or did it make its own choice?' |
| Stage 3 — Auto-refresh and history | Student combines auto-refresh and history into one long prompt. One part works, the other is broken. | 'The Watch For note suggests splitting these. What would happen if you wrote two shorter prompts instead of one long one?' |
| Stage 4 — Alert and credentials | Student hardcodes a threshold number without connecting it to the real-world reason they identified in Section 2. | 'Your Stage card asks for your threshold and what it means. Is the reason in your prompt, or just the number?' |
| Stage 5 — Polish for your user | Student copies a visual style from the demo without asking whether it suits the actual user they described. | 'Your user from Section 2 — does a dark sci-fi aesthetic match what they need? What would make them trust the data more?' |
Section 05
Credential security: what you need to know
⚠️ Review this section before any credentials are entered
The rules below apply to you as facilitator as much as to your student.
Make sure both of you understand them before Stage 4 of the project begins.
- The Adafruit IO API Key is the password to the sensor data account. Anyone who has it can read, write, or delete feed data.
- Real credentials must never be typed into claude.ai, pasted into the Student Workbook, or embedded in the HTML source code.
- The Settings panel built in Stage 4 is the correct place to enter real credentials. Values entered there stay in the browser session only and are never sent to Claude.
- If a key is accidentally exposed anywhere: go immediately to io.adafruit.com → My Account → API Keys and regenerate it.
Section 5 of the Student Workbook asks your student to explain the security risk in their own words. Do not skip this reflection — the ability to explain why a rule exists is more durable than the habit of following it.