Welcome

--:--recording — let's go

Week 2

Specs and self-portrait

the brief poses the problem

the spec is the contract

what changed this week?

DeepSeek Flash v4

Ten advances in mathematics and theoretical computer science

Qwen 3.8

today’s beats

explore, plan, implement, verify

interrogating the brief and spec with the agent, before it builds

putting each instruction in the right artefact

why a page rendering is no evidence that it’s right

demo: from brief and spec to the smallest interactive slice

demo: yes, and

Read this week’s hall-of-fame pick and the Assignment 1 brief and spec. Plan the smallest interactive explainer its subject could become: one idea, one mechanic, nothing else. Write the plan to PLAN.md — my working file, not the spec. Do not build yet.

then we leave it running and talk about specs

brief, spec, response, plan

defining some terms

the brief poses the problem (no single right answer)

the spec is the fixed contract that every response has to satisfy

your response is the particular thing you decide to make

the plan is a set of concrete steps to ‘build it out’

words; what do they even mean?

make claude argue with you

aka “adversarial review”

hand it the brief and spec before it builds anything: what’s ambiguous here, what did you assume, what have we missed?

back comes a list of decisions you didn’t know you were making

instructions are distributed

  1. the brief and spec: this deliverable, fixed on the course site
  2. CLAUDE.md: standing repo rules, alive across deliverables
  3. prompts and plans: this session’s decisions, alive for an afternoon
  4. the current session: what’s in the context right now

I made something, is it good?

could a human tell?

“make it look good” fails; “exactly one top-level heading” passes

every crit spec on the site is deliberately a mix of human- vs machine-checkable

/comp4020:start helps you turn the machine-checkable stuff into tests, so you can focus on the other stuff

Claude Code cheatsheet

shift+tab cycles the permission mode; the status bar names the one you’re in

manual: it asks before every edit and every command

accept edits: edits land unasked, commands still stop

plan: it reads and proposes, and edits stay blocked until you accept

auto: the course recommendation — a classifier vets each action instead of asking you

back to the demo

demo: happy with this plan?

before I switch across: what do you reckon it did?

then we read it together — the response it chose, and the decisions it made on our behalf

now you try

One thing this plan is still missing is ______.

thirty seconds with a neighbour, then one call goes into the plan

demo: build it

Add that to the plan, then build the smallest slice the plan describes. Run the checks and report what they say. Don’t let the scope grow.

then we leave it running and go looking at browsers

which box does what?

the browser builds another artefact

the source is what you wrote; the DOM is what the browser built from it, after parsing and repairing; the screen is what that DOM gets rendered to

details are complicated, but it’s worth knowing the concepts

(see how browsers work on MDN for the long version)

the source, in full

<!doctype html>
<html lang="en">
  <head>
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>How deep is the deep sea?</title>
  </head>
  <body>
    <nav><a href="/">home</a></nav>
    <h1>How deep is the deep sea?</h1>
    <img src="/anglerfish.avif" alt="An anglerfish lit by its own lure" />
  </body>
</html>

it renders, so it’s fine?

HTML parsing is error-tolerant by spec: unclosed tags get closed, misnested elements untangled, broken markup rendered anyway

which is why the starter template ships invariant checks: a declared language, a real title, a viewport meta, a nav landmark, one <h1>, alt text on every image

they run against dist/ — what actually ships, not what you wrote

so how do you see

what the browser built?

DevTools

Elements: the DOM the browser built, which is not your source file — it is what the browser is using

device toolbar: both marking viewports, 1920×1080 and 390×844 — every prototype, from C1 on

pnpm check: the invariants read dist/ (which is what actually ships)

Ben uses…

Ghostty

the (pseudo)terminal the agent runs in, native and fast, configured from one text file I can diff

Predict, then watch

your prediction

discuss with your neighbour: what’s gonna happen?

(hold the verdict until we’ve all seen it)

demo: read it against the spec

interactive means the visitor does something that changes what they see

how much did the spec and plan determine, and what still needs a person’s judgement?

we read what it reported, not what the page looks like

now you try

At 390×844, the one thing I would refuse to ship is ______.

thirty seconds with a neighbour, then one call goes straight back to the agent

that’s what assignment 1 is about

an interactive explainer of something you think more people should know — one strong idea, one dataset or mechanic, and nothing else

doesn’t have to be “real”

due noon, Monday 17 August

examples

Elevators: change the traffic and the algorithm, then watch the wait-time distribution move

Mechanical Watch: Ciechanowski takes a movement apart, one draggable diagram at a time

Waveforms: The Pudding, where the explainer plays the thing it is explaining

The Deep Sea: neal.fun, one scrollbar doing all the work

C2: unsolicited redesign

find a real organisation you like with a website you don’t, and build them a better one

for the crit: explain why yours is better

stack note: Astro becomes the course default with C2; any static stack you can defend is fine

don’t be a meat proxy

Gruhn, 3 August

the existential bit

the maths result we opened on: ten open problems, moved along by a model

whither humans?

the other half of the title

the agent writes the code; you decide what code there should be

what did this work change about who I want to be as a software developer? — every deliverable asks you that in writing

what’s yours: the response, the plan, the harness, the checks you wired in, the things you said yes (or no) to

deadline radar

this week: /comp4020:start for C2, then turn its spec into tests before you build

your week-3 cutoff: C2 live at its URL, reflection in the repo

noon, Monday 17 August: assignment 1 — same canvas, static and client-side

your Claude budget now resets Thursday 9am

the first one was this morning at 9 (everyone reset fresh)

also; cache set to 60min (up from 5min)

same weekly amount ($100), same cap; details on Ed

week 9: Monday groups

Monday 5 October is a public holiday, so neither Monday crit runs in its usual slot

Shítāo: Tuesday 6 October, 14:00–15:30, usual room

Bādà: Wednesday 7 October, 15:30–17:00, Room 3.05

your C8 cutoff moves with your session

tl;dr

the brief poses the problem, the spec is the fixed contract, the plan is yours

your instructions live in four places; don’t mix them up

source, DOM and screen are three different artefacts

software as self-portrait

ask your agent

ask until you can explain these back:

  • source, DOM and screen: where can they disagree, and which panel shows me
  • error tolerance: what will a browser forgive that a screen reader won’t
  • permission modes: which one am I in, and what can you do without asking
  • the brief and spec: what is fixed, and who is allowed to change it

See you in the studio