docs(deck): revision guide reconciling the lecture deck to shipped reality
The deck predates v0.8.3, the network-node pivot, and the flash pathology. Capture what breaks against the app/hardware (stale ADD layer names, pre-correction schedule, Web-Serial connect flow), the narrowed flow, and slide-by-slide target copy pinned to addLayers.ts and Landing.tsx so deck and app cannot re-drift. Co-Authored-By: Claude Opus 4.8 <[email protected]>
This commit is contained in:
Omar Sobh
co-authored by
Claude Opus 4.8
Claude Opus 4.8
parent
37a54521e8
commit
62e4a3b688
@@ -0,0 +1,159 @@
|
|||||||
|
# APESS 2026 — Lecture Deck Revision
|
||||||
|
|
||||||
|
**Follow-up to the deck summary.** What changed since the deck was written (ZeroClaw v0.1.0 →
|
||||||
|
v0.8.3, the network-node pivot, the failure-first reframe, and the flash pathology), the flow the
|
||||||
|
deck should now tell, and slide-by-slide target copy.
|
||||||
|
|
||||||
|
> **Authoritative sources — pull from these, do not retype from memory:**
|
||||||
|
> - ADD layer titles → `src/lib/addLayers.ts`
|
||||||
|
> - Schedule → `src/pages/Landing.tsx` (`PROGRAMME`)
|
||||||
|
> - Connect flow → the network-node model (web-chat-by-IP over LAN), not Web Serial
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. What needs to change
|
||||||
|
|
||||||
|
Grouped by severity. The deck's **spine is sound** — the perception loop, threshold-as-design,
|
||||||
|
the two-failure-modes block, and the vision slides all still hold. The failure-first block (deck
|
||||||
|
slides 13–17) is *more* central now, not less. What follows is only what breaks against the app
|
||||||
|
as shipped and the hardware as measured.
|
||||||
|
|
||||||
|
### 🔴 Wrong — contradicts the app or the programme
|
||||||
|
|
||||||
|
| # | Slide(s) | Deck says | Reality | Fix |
|
||||||
|
|---|---|---|---|---|
|
||||||
|
| C1 | 11, 22 | ADD layers: L1 Actor map · L2 Harness spec · L3 Decision graph · L4 Failure-mode analysis · L5 AI-native redesign | **L1 Domain & events · L2 Skills · L3 Policies · L4 Harness · L5 Loops** | Re-author both slides. The field→layer mapping on 11 collapses entirely — Harness moved to L4, L2 is Skills. Failure is now *woven through* L3/L4/L5, not a standalone layer. |
|
||||||
|
| C2 | 22, 23 | Modules at 15:00 / 16:00 / 17:00; lecture inside the afternoon | Lecture is a **separate 10:45–12:15 morning session**; hackathon **14:00–19:00**, modules ~14:45 / 16:10 / 17:40 | Retime slide 22; stop implying the lecture is part of the hack block. |
|
||||||
|
| C3 | 23 | "Open Chrome · Connect your kit · Web Serial · flash ZeroClaw to the UNO Q" | Students **already have the board** with a week of their own sensor work. *Omar* backs up → reflashes → provisions ZeroClaw. Students reach their node **over the LAN via web-chat-by-IP (HTTP + SSE)** — no Web Serial, no self-flash. `apess.redclaw.dev` URL still correct. | Rewrite the mechanism sentence; keep the URL/QR. |
|
||||||
|
|
||||||
|
### 🟡 Review — probably-wrong numbers/labels
|
||||||
|
|
||||||
|
| # | Slide(s) | Issue | Action |
|
||||||
|
|---|---|---|---|
|
||||||
|
| R1 | 2 | "ZeroClaw v0.1.0" + `latency_ms: 318` | We're on **v0.8.3**. 318 ms is a *cloud*-path figure; on-board warm tool call is **~3.8 s** (0.5B). Decide which path the slide shows and label it. |
|
||||||
|
| R2 | 2, 4, 9 | Model `claude-haiku-4-5` | Verify the actual model string in the shipped config; don't trust the deck. Provider "anthropic" is correct. |
|
||||||
|
| R3 | 10 | "WebSocket to browser" | Transport is **SSE**, not WebSocket (we specifically avoid the blocking `/webhook`). Say "streamed to the browser (SSE)". |
|
||||||
|
|
||||||
|
### 🟢 Careful reframe — new hardware truth
|
||||||
|
|
||||||
|
| # | Slide(s) | Issue | Action |
|
||||||
|
|---|---|---|---|
|
||||||
|
| H1 | 10 | LED matrix as an agent "Act" output in the loop | **Agent-triggered flashing hangs the chat turn** — openocd's SWD/GPIO activity poisons the turn's task (the flash physically lands, but the turn never acknowledges). So severity→LED must be driven by a **pre-flashed responder sketch the agent talks to**, not the agent re-flashing per event. Never demo "the agent flashes the matrix in the loop" — it visibly hangs. Flashing itself is demoed once, from the CLI, by the instructor. |
|
||||||
|
|
||||||
|
### 🟢 Fine as-is
|
||||||
|
Slides 1, 3, 5–9, 12–21. In particular slide 9's "Dragonwing makes the HTTP call directly, no UART
|
||||||
|
bridge" is **correct** to our architecture. Vibration bands (15/16) are already environment-tagged.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. How the flow should be
|
||||||
|
|
||||||
|
The deck's job narrows to one arc: **the sensor already thinks — now design it to fail well.**
|
||||||
|
The students spent a week making the board *sense*. The deck's payload is the turn from sensing to
|
||||||
|
*judgment under failure*, ending in the ADD as the deliverable. Seven beats:
|
||||||
|
|
||||||
|
1. **Hook** (1–2) — "what if your sensor could think?" → a real on-device result. *It already does;
|
||||||
|
here's proof from your board.*
|
||||||
|
2. **Ground the LLM** (3–4) — a function from situation-description to interpretation. Demystify.
|
||||||
|
3. **The loop** (5–10) — Perceive → Window → Threshold → Reason → Act. The thing they'll configure.
|
||||||
|
**Land the weight on Threshold (8): the trigger engine is the intelligence.**
|
||||||
|
4. **The deliverable** (11–12) — every runtime field maps to an ADD layer. The ADD is the design
|
||||||
|
language, not homework.
|
||||||
|
5. **The pivot — failure-first** (13–17) — building is easy; designing for the two failure modes is
|
||||||
|
the work. *This is the spine of the whole session and the school's own theme (Nardin's
|
||||||
|
robustness/resilience, Georgakis's "timely reaction").* A fail-safe must never degrade to
|
||||||
|
"nominal."
|
||||||
|
6. **Vision at scale** (18–21) — one board → bridges, hospitals, fault networks classifying
|
||||||
|
themselves. The constraint was never compute; it was assuming intelligence lived elsewhere.
|
||||||
|
7. **Handoff** (22–23) — the corrected schedule, then "connect to your node and start Module 1."
|
||||||
|
|
||||||
|
**What moved the flow:** the connect step (7) is no longer "flash the board" — the board is already
|
||||||
|
an agentic node when they sit down. The deck should say *meet the node you already have*, matching
|
||||||
|
the app's 14:25 "Meet your node" beat. And the failure block (5) is now explicitly the school's
|
||||||
|
Week-1/Week-3 through-line, not a generic caveat.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Slide-by-slide targets (only the ones that change)
|
||||||
|
|
||||||
|
### Slide 2 · Live output — *review numbers*
|
||||||
|
- Caption: **"Arduino UNO Q 4GB running ZeroClaw v0.8.3 — the same board at your seat."**
|
||||||
|
- If the JSON shows the **cloud** path: keep a sub-300 ms–ish latency but label it *cloud*.
|
||||||
|
- If it shows **on-device**: latency must read seconds, not milliseconds (~3.8 s warm, 0.5B).
|
||||||
|
- Verify `provider` and the model string against shipped config (R2).
|
||||||
|
|
||||||
|
### Slide 9 · Reason — *review model/latency only*
|
||||||
|
- Keep the architecture claim (direct HTTP from the Linux side, no UART bridge) — it's correct.
|
||||||
|
- Fix the footer model/latency to match slide 2's resolved values.
|
||||||
|
|
||||||
|
### Slide 10 · Act — *transport + LED reframe*
|
||||||
|
- Three channels stay. Change "WebSocket" → **"streamed to the browser (SSE)."**
|
||||||
|
- Reframe the LED channel: **"the agent talks to a pre-flashed responder sketch that owns the
|
||||||
|
matrix"** — it does not re-flash per event. (One-time flash is an instructor CLI step, off-deck.)
|
||||||
|
|
||||||
|
### Slide 11 · Output → ADD — *full re-author*
|
||||||
|
Map each output field to the **current** layers:
|
||||||
|
|
||||||
|
| field | layer |
|
||||||
|
|---|---|
|
||||||
|
| `classification` | **L3 · Policies** (what the decision authorises) |
|
||||||
|
| `reasoning` | **L1 · Domain & events** (the actor/event frame it's reasoning over) |
|
||||||
|
| `confidence` + `latency_ms` | **L4 · Harness** (the runtime envelope) |
|
||||||
|
| the loop cadence / cooldown | **L5 · Loops** |
|
||||||
|
| the skills it invoked | **L2 · Skills** |
|
||||||
|
|
||||||
|
Footer: *"Failure isn't a sixth layer — it's the question you ask of L3, L4, and L5."*
|
||||||
|
|
||||||
|
### Slide 22 · Your work today — *retime + relabel*
|
||||||
|
Layer chips: **L1 Domain & events · L2 Skills · L3 Policies · L4 Harness · L5 Loops.**
|
||||||
|
Schedule (verbatim from `Landing.tsx` `PROGRAMME`):
|
||||||
|
|
||||||
|
| time | block |
|
||||||
|
|---|---|
|
||||||
|
| 10:45–12:15 | Lecture (separate morning session) |
|
||||||
|
| 14:00 | Arrival & registration — boards backed up & reflashed while you register |
|
||||||
|
| 14:25 | Meet your node — the board you already know, now carrying an agent |
|
||||||
|
| 14:45 | Module 1 · Domain & events → **L1** |
|
||||||
|
| 16:10 | Module 2 · Skills & policies → **L2 + L3** (drive a real sensor, enumerate failure states, set the gate) |
|
||||||
|
| 17:40 | Module 3 · Harness, loops & submit → **L4 + L5** |
|
||||||
|
| 19:00 | Judging & award |
|
||||||
|
|
||||||
|
Judged on **rigour, not technical complexity** — keep that line.
|
||||||
|
|
||||||
|
### Slide 23 · Handoff — *rewrite mechanism*
|
||||||
|
- Keep: `apess.redclaw.dev` + QR.
|
||||||
|
- Replace the setup sentence with: **"Your board is already an agentic node. Open the app, connect
|
||||||
|
to your node on the workshop network, and start Module 1."**
|
||||||
|
- Delete: Web Serial, Chrome-only requirement, "flash ZeroClaw," OS-specific toolchain install.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. How it plays into the flow
|
||||||
|
|
||||||
|
- **C1 (layers)** is load-bearing for beats 4 and 7 — if the deck names layers the app doesn't, the
|
||||||
|
judging rubric and the student's document won't match what the slides promised. This is the same
|
||||||
|
drift that was a P0 bug in the app; fix the deck to the *same* single source (`addLayers.ts`).
|
||||||
|
- **C2/C3 (schedule + connect)** land in beat 7 (handoff). They're what students act on in the first
|
||||||
|
25 minutes; getting them wrong strands people at the door. The corrected flow also *recovers an
|
||||||
|
hour* by moving the lecture out of the afternoon.
|
||||||
|
- **H1 (LED/flash)** protects beat 3 (the loop demo). The loop is the deck's centrepiece; a live
|
||||||
|
agent-flash hang there would undercut the whole "it already thinks" promise. Demo the loop with a
|
||||||
|
pre-flashed responder; demo flashing once, from the CLI, as a separate instructor moment.
|
||||||
|
- **The failure block (beat 5)** is the payload the rest of the deck now serves. Everything before it
|
||||||
|
is setup for "design it to fail well"; everything after (the vision, the handoff) is the reward and
|
||||||
|
the call to action. Keep it dark, keep it central, and tie it explicitly to the school's own
|
||||||
|
resilience theme.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Checklist before the deck ships
|
||||||
|
|
||||||
|
- [ ] Slide 11 & 22 layer names match `src/lib/addLayers.ts` exactly.
|
||||||
|
- [ ] Slide 22 schedule matches `Landing.tsx` `PROGRAMME` (lecture 10:45, hack 14:00–19:00).
|
||||||
|
- [ ] Slide 23 has no Web-Serial / self-flash language; URL + QR retained.
|
||||||
|
- [ ] Slides 2/9 version = v0.8.3; model string verified against shipped config; latency labelled
|
||||||
|
cloud-vs-onboard.
|
||||||
|
- [ ] Slide 10 says SSE; LED channel = pre-flashed responder, not per-event flash.
|
||||||
|
- [ ] No slide implies the agent flashes the board inside the loop.
|
||||||
|
</content>
|
||||||
|
</invoke>
|
||||||
Reference in New Issue
Block a user