{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "factory-image-prompts-worked-example",
  "slug": "image-prompts-worked-example",
  "title": "Images as precise task evidence — worked example",
  "summary": "Detailed worked example with concrete prompts, observable outcomes, and the limits of the example.",
  "category": "Context",
  "tags": [
    "image-prompts",
    "examples"
  ],
  "sources": [
    {
      "label": "Images as precise task evidence — worked example",
      "url": "https://amber-willow-n64j.here.now/replay.html"
    }
  ],
  "sourceUnits": [
    "03-images/replay.html#What you're watching",
    "03-images/replay.html#Beat 1 · The drop",
    "03-images/replay.html#Beat 2 · The annotation IS the prompt",
    "03-images/replay.html#Beat 3 · The picture is the spec",
    "03-images/replay.html#Beat 4 · The bug report that shipped as a PR",
    "03-images/replay.html#Take the prompt home"
  ],
  "collection": "factory",
  "categoryId": "context",
  "wordCount": 934,
  "url": "/topics/factory-image-prompts-worked-example/",
  "markdownUrl": "/markdown/factory-image-prompts-worked-example.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/factory-image-prompts-worked-example.json",
  "headings": [
    {
      "id": "what-you-re-watching",
      "text": "What you're watching",
      "level": 2
    },
    {
      "id": "beat-1-the-drop",
      "text": "Beat 1 · The drop",
      "level": 2
    },
    {
      "id": "beat-2-the-annotation-is-the-prompt",
      "text": "Beat 2 · The annotation IS the prompt",
      "level": 2
    },
    {
      "id": "beat-3-the-picture-is-the-spec",
      "text": "Beat 3 · The picture is the spec",
      "level": 2
    },
    {
      "id": "beat-4-the-bug-report-that-shipped-as-a-pr",
      "text": "Beat 4 · The bug report that shipped as a PR",
      "level": 2
    },
    {
      "id": "take-the-prompt-home",
      "text": "Take the prompt home",
      "level": 2
    }
  ],
  "markdown": "# Images as precise task evidence — worked example\n\nDetailed worked example with concrete prompts, observable outcomes, and the limits of the example.\n\n## What you're watching\n\n**YOU** rows are the human's turns; **AGENT** rows are the agent's; the italic lines are workshop commentary. Every prompt is quoted verbatim from a prior session's history, the screenshots are the actual captures from those sessions, and the agent turns summarize what those sessions did — nothing here is invented. The full prompt library and setup guide live on the [section guide](https://amber-willow-n64j.here.now/index.html).\n\n## Beat 1 · The drop\n\nYou\n\nHit the CleanShot hotkey on the running app. Draw ONE fat red arrow at the element in question. Drag the capture from the annotate overlay straight into the agent's prompt.\n\nThe whole loop — capture, annotate, drop — takes seconds. Fast enough to use for every UI-shaped prompt.\n\nAgent\n\nThe drop renders as an inline marker — `[Image #1]` in Claude Code and pi. The Codex CLI rewrites the same drag into a file header instead:\n\n``` text\n# Files mentioned by the user:\n## capture.png:\n~/screenshots/capture.png\n```\n\nEither way the model gets the pixels. The rendering difference only matters when you script prompts.\n\nYou\n\nProjector day, so drag-and-drop is awkward — grab the newest capture's path from the shell instead:\n\n``` text\ndir=\"${CLEANSHOT_DIR:-$HOME/screenshots}\"\nls -t \"$dir\" | head -3\nprintf '%s' \"$dir/$(ls -t \"$dir\" | head -1)\" | pbcopy\necho \"newest capture path copied — paste it into your agent prompt\"\n```\n\nA pasted file path works because the image is data, not decoration — an agent with filesystem access reads the actual pixels.\n\n## Beat 2 · The annotation IS the prompt\n\nYou\n\n![A launcher command list with a red arrow pointing at the top row and a large red text callout reading: This is way too dramatic. Make it extremely subtle. Also, when you return the focus to the first row, it should go away. Its appear/disappear behavior should be smooth.](https://amber-willow-n64j.here.now/images/arrow-design-feedback.png)\n\nCleanShot's text tool, used mid-session: the feedback is typed directly on the capture.\n\n``` text\n[Image #1] Do what the annotation says.\n```\n\nThe arrow marks the element; the callout typed on the image carries the whole instruction. The typed prompt shrinks to five words.\n\nAgent\n\nEverything it needs is in the pixels: the arrowed top row is the subject, and the callout is the instruction — too dramatic, make it extremely subtle, make it go away when focus returns to the first row, smooth the appear/disappear.\n\nWhen the annotation and the intent collapse into one image, there is nothing left to describe in prose.\n\n## Beat 3 · The picture is the spec\n\nA different prior session, a different repo: a workspace sidebar that needed a design pass. No paragraph described the sidebar.\n\nYou\n\n``` text\n[Image #1] Ask /oracle-packx for some suggestions on how we can make the\nworkspace sidebar much more \"at a glance\" useful then create a /web-choices\nfrom its suggestions and implement my choices once they're ready\n```\n\nVerbatim, and the whole prompt. `/oracle-packx` and `/web-choices` are the author's local slash commands — the portable shape is on the [section guide](https://amber-willow-n64j.here.now/index.html).\n\nAgent\n\nConsulted for suggestions with the screenshot as the baseline, came back with five design directions, rendered them as a visual picker, and implemented the saved choices.\n\nThe baseline screenshot carried the entire spec. The picture answered every \"what does it look like now?\" question before it was asked.\n\n## Beat 4 · The bug report that shipped as a PR\n\nThe finale, from a prior session on a desktop launcher app. The bug: while typing in the main menu input, focus sometimes jumps off the first item down to a lower row. Exactly the kind of bug prose describes badly.\n\nYou\n\nCapture the failure state. One fat arrow at the row that wrongly holds selection.\n\n![A dark launcher window with 'This is' typed in the search field. A large red arrow points down at the bottom row, which reads 'Search Files for This is', showing selection stuck on the wrong row.](https://amber-willow-n64j.here.now/images/arrow-bug-report.png)\n\nThe screenshot that was the bug report.\n\n``` text\n/goal [Image #1] --- ensure that as you're typing in the main menu input, that\nthe first item in the list always stays focused. Way too often, we're running\ninto scenarios like this where the focused item jumps down to \"search files\"\nor something. /oracle-packx then implement\n```\n\nThat was the entire bug report. \"Scenarios like this\" points at the picture: the arrow answers *which element*, the sentence answers *what you want*, and the slash commands chain the plan.\n\nAgent\n\nOne conversation, no follow-up prompts: investigated the focus handling, consulted an external model with the screenshot in the context bundle, implemented the fix, verified it live in the running app, committed, and opened a pull request.\n\nThe fix shipped as a PR from a one-sentence prompt because the screenshot carried the context.\n\n## Take the prompt home\n\nThe money artifact above uses the author's local slash commands. This is the portable version — the same prompt with those commands removed, ready to paste into any image-capable agent:\n\n``` text\n[Image #1] --- ensure that as you're typing in the main menu input, the first\nitem in the list always stays focused. Way too often we hit scenarios like\nthis where focus jumps down to the row the arrow points at. Investigate,\nimplement, verify in the running app.\n```\n\nAll five reusable prompt shapes, the setup steps, and the caveats are on the [section guide](https://amber-willow-n64j.here.now/index.html). To teach your agent to *read* annotated screenshots this way, hand it [agent.md](https://amber-willow-n64j.here.now/agent.md)."
}
