{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "foundations-design-video-qa-field-guide",
  "slug": "design-video-qa-field-guide",
  "title": "Design, Video, and QA Story Field Guide",
  "summary": "Convert taste, screenshots, narrated videos, and weird user behavior into Codex-ready implementation stories.",
  "category": "Planning",
  "tags": [
    "field guide",
    "design video qa"
  ],
  "sources": [
    {
      "label": "Agent foundations: Trust current source and capture design decisions (authorized access required)",
      "url": "https://codex-workshop-followup.pages.dev/lesson-04.html"
    },
    {
      "label": "Agent foundations: Explore software through perspectives and runtime QA (authorized access required)",
      "url": "https://codex-workshop-followup.pages.dev/lesson-05.html"
    },
    {
      "label": "Agent foundations: Use images, video, and task-shaped model routing (authorized access required)",
      "url": "https://codex-workshop-followup.pages.dev/lesson-06.html"
    },
    {
      "label": "Agent foundations: Preserve contracts and state machines while code changes (authorized access required)",
      "url": "https://codex-workshop-followup.pages.dev/lesson-11.html"
    }
  ],
  "sourceUnits": [
    "field-guides/guides.mjs#design-video-qa/overview",
    "field-guides/guides.mjs#design-video-qa/decision",
    "field-guides/guides.mjs#design-video-qa/agentPrompt",
    "field-guides/guides.mjs#design-video-qa/stories",
    "field-guides/guides.mjs#design-video-qa/tips",
    "field-guides/guides.mjs#design-video-qa/refs"
  ],
  "collection": "foundations",
  "categoryId": "planning",
  "wordCount": 440,
  "url": "/topics/foundations-design-video-qa-field-guide/",
  "markdownUrl": "/markdown/foundations-design-video-qa-field-guide.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/foundations-design-video-qa-field-guide.json",
  "headings": [
    {
      "id": "choose-the-right-mechanism",
      "text": "Choose the right mechanism",
      "level": 2
    },
    {
      "id": "agent-ready-prompt",
      "text": "Agent-ready prompt",
      "level": 2
    },
    {
      "id": "applied-stories",
      "text": "Applied stories",
      "level": 2
    },
    {
      "id": "reference-image-to-ui",
      "text": "Reference image to UI",
      "level": 3
    },
    {
      "id": "narrated-bug-report",
      "text": "Narrated bug report",
      "level": 3
    },
    {
      "id": "5-monkeys-qa-swarm",
      "text": "5 Monkeys QA swarm",
      "level": 3
    },
    {
      "id": "tips-and-gotchas",
      "text": "Tips and gotchas",
      "level": 2
    },
    {
      "id": "references",
      "text": "References",
      "level": 2
    },
    {
      "id": "related-principles",
      "text": "Related principles",
      "level": 2
    }
  ],
  "markdown": "# Design, Video, and QA Story Field Guide\n\n> Original source pages and recordings require authorized access. The full article text here is public.\n\nConvert taste, screenshots, narrated videos, and weird user behavior into Codex-ready implementation stories.\n\nUse this when words are weak and Codex needs visual requirements plus browser-verifiable acceptance criteria.\n\n## Choose the right mechanism\n\n| Mechanism | Use when | Agent responsibility | Artifact |\n|---|---|---|---|\n| design.md | Durable taste contract | Style DNA, type, color, layout | design.md |\n| Image reference | Human-selected direction | Implement one concrete look | .notes/design/reference.png |\n| Video requirements | Narrated UX behavior | Extract acceptance criteria and edge cases | .goals/<feature>-video.md |\n| QA swarm | Weird-path exploration | Personas, broken paths, browser receipts | .notes/qa/ |\n\n## Agent-ready prompt\n\n```text\nTreat the visual artifact as requirements, not decoration.\nExtract acceptance criteria, user stories, responsive states, and proof moves.\nImplement only the selected direction.\nVerify in browser with screenshots/logs.\nWrite the durable contract to design.md, .goals/<feature>.md, or .notes/qa/<flow>.md depending on the task.\n```\n\n## Applied stories\n\n### Reference image to UI\n\n**Role:** Product engineer\n\nThe team can recognize the desired look but cannot write the CSS spec.\n\n**Agent brief:** Ask Codex to distill the selected image into design.md, implement one route, then browser-proof the result.\n\n**Done when:**\n\n- design.md update\n- implemented route\n- desktop/mobile screenshots\n- diff review\n\n### Narrated bug report\n\n**Role:** Full-stack developer\n\nA PM records cart behavior that is faster to show than explain.\n\n**Agent brief:** Extract requirements from video into a goal file, implement behavior, and prove cart states in browser.\n\n**Done when:**\n\n- video-derived goal\n- acceptance criteria\n- browser proof\n- test/typecheck log\n\n### 5 Monkeys QA swarm\n\n**Role:** QA-minded frontend lead\n\nHappy path passes, but users hit weird navigation and state sequences.\n\n**Agent brief:** Launch persona-based QA workers that write reproducible findings, then collate only high-signal bugs.\n\n**Done when:**\n\n- persona findings\n- dedupe summary\n- screenshots\n- repro steps\n\n## Tips and gotchas\n\n- Do not ask Codex to invent taste from nothing; hand it references and constraints.\n- A video should become acceptance criteria, not a brittle click macro.\n- Keep visual QA disposable until the flow stabilizes; promote only stable checks to tests.\n- Every visual/design story should end with browser proof across relevant viewports.\n\n## References\n\n- [Impeccable](https://impeccable.style/)\n- [Inspiration board](https://inspiration-board.pages.dev/)\n- [OpenAI Codex Figma/frontend post](https://developers.openai.com/codex)\n- [Playwright screenshots](https://playwright.dev/docs/screenshots)\n\n## Related principles\n\n- [Trust current source and capture design decisions](/topics/foundations-source-truth-and-design/)\n- [Explore software through perspectives and runtime QA](/topics/foundations-perspective-qa-and-testing/)\n- [Use images, video, and task-shaped model routing](/topics/foundations-multimodal-design-and-model-routing/)\n- [Preserve contracts and state machines while code changes](/topics/foundations-contracts-state-machines-and-code/)"
}
