The Spec

The proposal named two capabilities: toast-appearance and toast-lifecycle. OpenSpec has already turned those into spec files — one per capability, each sitting in its own folder:

Note: What goes into the spec often emerges from exploration. When you explored "should I use Postgres or SQLite?", the tradeoffs you surfaced (offline, single user, embedded) become the constraints you document in the spec. Exploration surfaces the questions; the spec captures the answers.

openspec/changes/toast-notifications/
├── .openspec.yaml
├── proposal.md
├── toast-appearance/
│   └── spec.md
└── toast-lifecycle/
    └── spec.md

Open both and read them before moving on.

Each spec is structured the same way: a requirement stated plainly, then scenarios in WHEN/THEN format. toast-appearance covers what toasts look like — the four variants, their colors and icons, where they sit on screen, how they animate in. toast-lifecycle covers how they behave over time — auto-dismiss after 3 seconds, click to close, the exit animation before removal from the DOM.

This is where the second a-ha happens.

Look at the auto-dismiss scenario: when a toast has been visible for 3 seconds, it begins its exit animation and is removed from the DOM. That's not just "dismiss after 3 seconds" — it's a sequencing decision. The animation plays first. The DOM removal happens after. Without this written down, the AI might remove the element immediately and skip the animation entirely. It would be a reasonable guess. It would also be wrong.

Every WHEN/THEN in these files is a decision that previously lived in your head or got made silently by the AI. Now it's explicit. Now the AI reads it before it writes a line.

If a scenario is missing or wrong, edit it now. In lesson 05 you'll write the design doc — how all of this actually gets built.