Design, Video, and QA Story Field Guide

Convert taste, screenshots, narrated videos, and weird user behavior into Codex-ready implementation stories.

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

Convert taste, screenshots, narrated videos, and weird user behavior into Codex-ready implementation stories.

Use this when words are weak and Codex needs visual requirements plus browser-verifiable acceptance criteria.

Choose the right mechanism

Mechanism Use when Agent responsibility Artifact
design.md Durable taste contract Style DNA, type, color, layout design.md
Image reference Human-selected direction Implement one concrete look .notes/design/reference.png
Video requirements Narrated UX behavior Extract acceptance criteria and edge cases .goals/<feature>-video.md
QA swarm Weird-path exploration Personas, broken paths, browser receipts .notes/qa/

Agent-ready prompt

Treat the visual artifact as requirements, not decoration.
Extract acceptance criteria, user stories, responsive states, and proof moves.
Implement only the selected direction.
Verify in browser with screenshots/logs.
Write the durable contract to design.md, .goals/<feature>.md, or .notes/qa/<flow>.md depending on the task.

Applied stories

Reference image to UI

Role: Product engineer

The team can recognize the desired look but cannot write the CSS spec.

Agent brief: Ask Codex to distill the selected image into design.md, implement one route, then browser-proof the result.

Done when:

  • design.md update
  • implemented route
  • desktop/mobile screenshots
  • diff review

Narrated bug report

Role: Full-stack developer

A PM records cart behavior that is faster to show than explain.

Agent brief: Extract requirements from video into a goal file, implement behavior, and prove cart states in browser.

Done when:

  • video-derived goal
  • acceptance criteria
  • browser proof
  • test/typecheck log

5 Monkeys QA swarm

Role: QA-minded frontend lead

Happy path passes, but users hit weird navigation and state sequences.

Agent brief: Launch persona-based QA workers that write reproducible findings, then collate only high-signal bugs.

Done when:

  • persona findings
  • dedupe summary
  • screenshots
  • repro steps

Tips and gotchas

  • Do not ask Codex to invent taste from nothing; hand it references and constraints.
  • A video should become acceptance criteria, not a brittle click macro.
  • Keep visual QA disposable until the flow stabilizes; promote only stable checks to tests.
  • Every visual/design story should end with browser proof across relevant viewports.

References

Source references