---
schema_version: 1
revision: "22ce5d34dbcb5a78"
id: "foundations-video-requirements-playbook"
title: "Video as requirements playbook"
---

# Video as requirements playbook

> Original source pages and recordings require authorized access. The full article text here is public.

Web developers already debug behavior in running apps, not just in source files. A narrated screen recording gives an agent the missing layer: what the user clicked, typed, expected, noticed, and wanted changed, then turns that into a concrete QA story and implementation brief.

[Core principles](/topics/foundations-contracts-state-machines-and-code/)

## Copy-paste workflow

**When to use:** When showing-and-narrating is faster than writing a perfect spec. Record yourself using the app while speaking intent, then have a multimodal model extract acceptance criteria and edge cases as agent-ready requirements.

### Copy-paste prompt

```text
I'm going to turn a narrated screen recording into agent-ready requirements instead of writing a perfect spec.

1. I will record a short narrated walkthrough of <APP/FEATURE>: I point, click, and talk through my intent and the outcomes I want.

2. Feed that recording to a multimodal model (Gemini, per the workshop) and ask it to extract a structured requirements checklist:
     - acceptance criteria
     - the user flow (step by step)
     - the specific clicks / typing / layout changes shown
     - responsive behavior
     - edge cases

3. Output a REPEATABLE, agent-ready requirements checklist (a QA story) I can hand to a coding agent.

Framing: the durable assets are the natural-language contract + the resulting diff — NOT the generated code. Don't over-specify HOW to verify; give clear outcomes and keep my QA judgment in the loop.

Guardrail: strip sensitive data first — video can expose more than you expect (open tabs, tokens, notifications, file paths).
```

### How it works
- Record a short narrated walkthrough — point, click, and talk through intent and desired outcomes — which is often faster than writing a perfect spec.
- Feed it to a multimodal model (Gemini, per the workshop) and extract acceptance criteria, the user flow, the clicks/typing/layout changes, responsive behavior, and edge cases.
- The output is a repeatable, agent-ready requirements checklist (a QA story).
- Under the throwaway-artifact mindset, the durable asset is the natural-language contract + the diff, not the generated code; don't over-specify how to verify — give clear outcomes and keep your QA judgment in the loop.
- Caution: strip sensitive data before uploading; video can expose more than you expect.
- Reference: [AGENTS.md](https://developers.openai.com/codex/guides/agents-md), [OpenAI Codex](https://github.com/openai/codex).

## Reusable skill

Install as `~/.agents/skills/video-as-requirements/SKILL.md`, then restart Codex.

```markdown
---
name: video-as-requirements
description: Trigger when a narrated screen recording captures intent better than a written spec — feed the video to a multimodal model to extract acceptance criteria, the user flow, and edge cases as an agent-ready requirements checklist. Do NOT upload videos containing sensitive data.
---

# Video as requirements

Turn a narrated screen recording into agent-ready requirements. When showing-and-narrating beats writing a perfect spec, record the app in use and let a multimodal model extract the contract.

## Steps

1. Record a short narrated walkthrough of the app: point, click, and talk through intent and desired outcomes.

2. Feed the recording to a multimodal model (Gemini, per the workshop) and ask it to extract a structured checklist:
   - acceptance criteria
   - the user flow (step by step)
   - the specific clicks / typing / layout changes shown
   - responsive behavior
   - edge cases

3. Output a REPEATABLE, agent-ready requirements checklist (a QA story) to hand to a coding agent.

## Framing
- The durable assets are the natural-language contract + the resulting diff — NOT the generated code.
- Don't over-specify HOW to verify; give clear outcomes and keep human QA judgment in the loop.

## Guardrails
- STRIP sensitive data before uploading — video can expose more than you expect (open tabs, tokens, notifications, file paths). Do NOT upload videos containing sensitive data.
```

## Scenarios

### Convert a narrated checkout bug into a fixable QA story

**Role:** As a frontend engineer maintaining a Next.js commerce app

A product manager records a two-minute walkthrough on localhost showing a cart drawer, promo-code input, shipping estimate panel, and checkout button. They narrate that the drawer jumps on mobile, the promo error disappears too fast, and the checkout button should stay disabled until shipping is selected.

> As a mobile shopper, I want the cart drawer, promo-code error, shipping estimate, and checkout enabled state to behave predictably, so that I can recover from mistakes and complete checkout without guessing what changed.

#### Agent brief

```text
You are implementing from a narrated video requirements artifact. First inspect the current app source and existing tests; do not trust stale notes. Use the video-derived QA story as the natural-language contract. Create or update `.goals/cart-video-requirements.md` with: user flow, acceptance criteria, responsive behavior, edge cases, and what evidence will prove the fix. Then implement only the behavior described: stable mobile drawer layout, persistent promo-code error state until corrected or dismissed, shipping selection as the gate for enabling checkout, and no unrelated redesign. Run the project’s normal lint/test/build commands discovered from package scripts. Start the local dev server and verify the flow in a browser. Produce a final review artifact containing the git diff summary, commands run, browser proof, and any remaining risks.
```

#### Implementation references

[Open reference](/topics/foundations-video-requirements-playbook/)

[Open reference](/topics/foundations-video-requirements-playbook/)

[Open reference](/topics/foundations-contracts-state-machines-and-code/)

[Open reference](/topics/foundations-contracts-state-machines-and-code/)

[Open reference](/topics/foundations-video-requirements-playbook/)

```text
package.json scripts: test, lint, build, dev
```

```text
git diff
```

#### Browser verification

Use a local browser or CMUX browser pane against the dev server. Capture an accessibility snapshot of the cart drawer, click the cart trigger, fill the promo-code field with an invalid code, click apply, resize or emulate mobile width, select shipping, and evaluate whether the checkout button disabled/enabled state matches the video-derived contract. Save a screenshot or concise browser log as proof.

#### Definition of done

- A checked-in or local review artifact that restates the video-derived QA story and acceptance criteria
- Passing lint/test/build output from the repo’s own scripts
- Browser proof showing invalid promo behavior, mobile drawer stability, shipping selection, and checkout button state
- A git diff review summary focused on the changed modules and any tests added or updated

#### Failure modes and mitigations

- The agent treats the video as a brittle click recorder and hard-codes selectors or exact timing; mitigate by extracting intent, user actions, expected behavior, responsive behavior, and edge cases before coding.
- The agent redesigns the cart instead of fixing the contract; mitigate by requiring source inspection first and limiting changes to behavior described by the narrated walkthrough.

### Turn a dashboard walkthrough into responsive UI requirements

**Role:** As a full-stack web developer owning a SaaS analytics dashboard

A customer success lead records a narrated walkthrough of a dashboard where they filter by date range, expand a table row, collapse search results on narrow screens, and point out that the summary cards reorder badly on tablet widths.

> As an account manager reviewing customer metrics, I want filters, expandable rows, collapsed search results, and responsive summary cards to preserve context across screen sizes, so that I can investigate an account without losing my place.

#### Agent brief

```text
Use the narrated walkthrough as requirements, not as a polished spec. Extract a QA story with the exact user flow, expected visual/layout behavior, responsive breakpoints observed in the video, and edge cases. Inspect the current dashboard code, routing, state ownership, and any existing browser tests. Implement the smallest change that preserves filter state, keeps expanded row context stable, makes search results collapse predictably on narrow screens, and improves tablet card ordering without changing unrelated dashboard styling. Run the repo’s normal verification commands. Then run the dashboard in a browser and prove the flow works at desktop, tablet, and mobile widths. Final output must include the diff summary plus browser evidence, not a generic success claim.
```

#### Implementation references

[Open reference](/topics/foundations-video-requirements-playbook/)

[Open reference](/topics/foundations-video-requirements-playbook/)

[Open reference](/topics/foundations-contracts-state-machines-and-code/)

[Open reference](/topics/foundations-contracts-state-machines-and-code/)

[Open reference](/topics/foundations-video-requirements-playbook/)

```text
AGENTS.md or agents.md if present
```

```text
package.json scripts
```

```text
git diff
```

#### Browser verification

Use Playwright if the repo already has it, otherwise use a local browser or agent-browser-style workflow: snapshot the dashboard, click the date filter, fill or select the target range, expand a row, resize to tablet and mobile, and evaluate whether the visible labels, expanded state, and collapsed search results match the QA story. Do not add a new browser framework just for this scenario unless the repo already uses one.

#### Definition of done

- A video-derived QA story with user actions, expected behavior, responsive behavior, and edge cases
- Passing project verification commands
- Browser proof at desktop, tablet, and mobile widths
- A diff-driven review note explaining which state/module boundaries changed and why

#### Failure modes and mitigations

- The agent over-specifies verification mechanics instead of outcomes; mitigate by keeping acceptance criteria outcome-based and using browser proof only as evidence.
- The agent ignores current code structure and adds duplicate dashboard state; mitigate by requiring source-of-truth code inspection and preserving existing module/state boundaries where practical.

### Use a video bug report to update guardrails after the fix

**Role:** As a tech lead supervising agent-assisted feature work

A teammate records a narrated video of a localhost onboarding flow where invite acceptance, workspace creation, and the empty-state screen drift from the intended product contract. Previous agents have fixed similar flows but keep missing the same auth and empty-state constraints.

> As a team admin accepting an invite, I want the onboarding flow to preserve auth context, create or join the right workspace, and show the correct empty state, so that first-run setup feels trustworthy.

#### Agent brief

```text
Treat the video as evidence for a natural-language contract. Extract the intended onboarding states and transitions from the narration: invite opened, auth checked, workspace joined or created, empty state shown, and error or retry states if present. Inspect the current code and identify the modules that own auth, workspace creation, routing, and empty-state rendering. Implement the smallest fix that satisfies the contract. After verification, review the git diff as the primary artifact. Then update `agents.md` or `AGENTS.md` only if the mistake reveals a reusable project-specific guardrail, such as where onboarding state must live or which module owns invite acceptance. Keep the guardrail short and grounded in this actual mistake.
```

#### Implementation references

[Open reference](/topics/foundations-contracts-state-machines-and-code/)

[Open reference](/topics/foundations-contracts-state-machines-and-code/)

[Open reference](/topics/foundations-video-requirements-playbook/)

[Open reference](/topics/foundations-video-requirements-playbook/)

```text
AGENTS.md or agents.md if present
```

```text
git diff
```

```text
package.json scripts
```

#### Browser verification

Browser proof is useful because onboarding is flow/state behavior. In a local browser, follow the invite URL or mocked invite route, complete the auth path using safe local test credentials or seeded state, click through workspace creation or join, and capture the final empty-state screen. If authenticated browser state is required, use a live browser/CMUX browser pane carefully and do not expose real tokens, QR codes, customer data, or private notifications.

#### Definition of done

- A compact onboarding state contract extracted from the video
- Passing verification commands and a browser receipt of the invite-to-empty-state flow
- A git diff summary suitable for fresh-session critique
- A minimal guardrail update only if it captures a real repeated project constraint

#### Failure modes and mitigations

- The agent dumps a broad rulebook into AGENTS.md; mitigate by allowing only short, project-specific guardrails learned from this actual video-backed failure.
- The agent uses real authenticated data casually during browser verification; mitigate by using local seeded data or sanitized test accounts and stripping sensitive information from videos and logs.

## Implementation notes

- Start by extracting a natural-language contract from the video before editing code. The contract should describe outcomes, user flow, responsive behavior, and edge cases; it should not become a brittle macro recording.
- Inspect the live source before implementation. The course material is explicit that code is the source of truth when implementation details matter.
- For web app work, browser proof matters when the requirement is visual, interactive, responsive, authenticated, or stateful. Use a local browser, CMUX browser pane, existing Playwright setup, or agent-browser-style snapshot/click/fill/evaluate workflow depending on what the repo already supports.
- Keep generated code disposable but preserve durable assets: the video-derived contract, module/state boundaries, tests or verification artifacts, browser receipts, and the reviewed diff.
- Strip sensitive data before uploading video. Screen recordings can leak tabs, tokens, paths, notifications, local QR codes, customer data, and auth state.
- Do not add new permanent QA infrastructure for unstable UI unless the project already has that direction. A short QA story plus browser receipt can be enough for fast-moving product work.
- Use `agents.md` or `AGENTS.md` as a living guardrail only when a real repeated mistake or project constraint emerges. Keep it small.

## Boundaries and caveats

- Do not present NotebookLM, Codex approvals/security, or Codex Skills documentation as taught workflows for this topic beyond the existing local skill artifact.
- Do not require Agent Browser or Playwright as mandatory tools for every scenario; use them only when browser proof fits and the repo or workflow already supports them.
- Do not treat video as a selector-level macro recorder. Extract intent and behavior, then verify outcomes.
- Do not over-specify exact verification internals when a clear outcome plus browser evidence is enough.
- Do not casually use authenticated browsers, local QR codes, secrets, customer data, or broad permissions in video capture or browser validation.
- Do not let AGENTS.md become a giant upfront rulebook. Update it from real mistakes and constraints only.

## Agent reference map

### Video as requirements prompt

Use this as the user-facing extraction prompt: record a narrated walkthrough, extract acceptance criteria, user flow, clicks/typing/layout changes, responsive behavior, and edge cases.

[Open reference](/topics/foundations-video-requirements-playbook/)

### Video as requirements Codex skill

Use this when packaging the workflow as a reusable local agent skill with guardrails around sensitive video data.

[Open reference](/topics/foundations-video-requirements-playbook/)

### Lesson 11 validated references

Treat this as ground truth for taught concepts: natural-language contracts, video-as-requirements, diff-driven review, modular/state-machine boundaries, living guardrails, and disposable generated code.

[Open reference](/topics/foundations-contracts-state-machines-and-code/)

### Lesson 11 validation notes

Use this to avoid reintroducing tools and claims that were mentioned but not taught as workflows in the final lesson.

[Open reference](/topics/foundations-contracts-state-machines-and-code/)

### Lesson 05 browser QA context

Use this only for the supporting browser-work angle: perspective-based QA, weird-path exploration, browser-driving agents, CMUX state, and video-driven intent extraction.

[Open reference](/topics/foundations-five-monkeys-playbook/)

### CMUX CLI surface

Use when the agent needs a visible local pane or browser-oriented workspace receipt; inspect state before acting and avoid inventing flags.

[Open reference](/topics/foundations-cmux-orchestrate-playbook/#command-reference)

### Local verification commands

Discover and run the repo’s actual scripts instead of inventing a test command.

```text
cat package.json
```

### Diff-driven review

Use the final git diff as the primary review artifact, then hand goal plus diff to a fresh session for critique when the change is risky.

```text
git diff
```

## Original references

- [Agent foundations: Preserve contracts and state machines while code changes (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-11.html)
