{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "factory-image-prompts",
  "slug": "image-prompts",
  "title": "Images as precise task evidence",
  "summary": "Use a marked screenshot to identify the target, a sentence to express intent, and a running-app check to prove the change.",
  "category": "Context",
  "tags": [
    "image",
    "factory"
  ],
  "sources": [
    {
      "label": "Images as precise task evidence",
      "url": "https://amber-willow-n64j.here.now/"
    },
    {
      "label": "Companion lesson",
      "url": "https://proud-anchor-53zn.here.now/learn.html#q2-annotated-image-prompt"
    }
  ],
  "sourceUnits": [
    "03-images/index.html#TL;DR",
    "03-images/index.html#Why one arrow beats a paragraph",
    "03-images/index.html#Appendix",
    "03-images/index.html#How agents ingest the drop",
    "03-images/index.html#What good captures look like",
    "03-images/index.html#Check what leaves your machine",
    "learn.html#q2-annotated-image-prompt"
  ],
  "collection": "factory",
  "categoryId": "context",
  "wordCount": 1223,
  "url": "/topics/factory-image-prompts/",
  "markdownUrl": "/markdown/factory-image-prompts.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/factory-image-prompts.json",
  "headings": [
    {
      "id": "related-working-material",
      "text": "Related working material",
      "level": 2
    },
    {
      "id": "tl-dr",
      "text": "TL;DR",
      "level": 2
    },
    {
      "id": "why-one-arrow-beats-a-paragraph",
      "text": "Why one arrow beats a paragraph",
      "level": 2
    },
    {
      "id": "how-agents-ingest-the-drop",
      "text": "How agents ingest the drop",
      "level": 2
    },
    {
      "id": "what-good-captures-look-like",
      "text": "What good captures look like",
      "level": 2
    },
    {
      "id": "check-what-leaves-your-machine",
      "text": "Check what leaves your machine",
      "level": 2
    },
    {
      "id": "appendix",
      "text": "Appendix",
      "level": 2
    },
    {
      "id": "limits-caveats",
      "text": "Limits & caveats",
      "level": 3
    },
    {
      "id": "operating-practice",
      "text": "Operating practice",
      "level": 2
    },
    {
      "id": "point-at-the-visual-problem",
      "text": "Point at the visual problem",
      "level": 3
    },
    {
      "id": "what-to-notice",
      "text": "What to notice",
      "level": 4
    },
    {
      "id": "try-this",
      "text": "Try this",
      "level": 4
    },
    {
      "id": "concept",
      "text": "Concept",
      "level": 4
    },
    {
      "id": "reflection",
      "text": "Reflection",
      "level": 4
    },
    {
      "id": "links-shared-for-this-topic",
      "text": "Links shared for this topic",
      "level": 4
    }
  ],
  "markdown": "# Images as precise task evidence\n\nUse a marked screenshot to identify the target, a sentence to express intent, and a running-app check to prove the change.\n\n## Related working material\n\n- [Images as precise task evidence — prompts and exercises](/topics/factory-image-prompts-practice/)\n- [Images as precise task evidence — questions and tradeoffs](/topics/factory-image-prompts-questions/)\n- [Images as precise task evidence — worked example](/topics/factory-image-prompts-worked-example/)\n\n## TL;DR\n\n- A capture→annotate→drop workflow: CleanShot hotkey, one fat red arrow, drag the image straight into the agent prompt.\n- You walk away with five copy-paste prompt shapes — including the two real prompts where a screenshot plus one sentence drove a bug fix all the way to a pull request.\n- The one move: when a prompt sentence starts describing a screen location (\"the row near the bottom…\"), stop typing and hit the capture hotkey instead.\n\n Have your agent adopt this — paste this into it:\n\n``` text\nFetch https://amber-willow-n64j.here.now/agent.md?raw and follow it to set up the screenshot-reading protocol in my current project. Run the success check at the end and show me the result.\n```\n\n## Why one arrow beats a paragraph\n\nSay your app's launcher sometimes moves focus to the wrong row while you type. Describe that in words alone — \"when I type in the menu, the selection sometimes jumps down to another item\" — and the agent must guess: which menu? which item? at what moment? A real session skipped the guessing: the entire bug report was the annotated screenshot in card 1 plus one sentence, and the session chained investigation, an external model consult, the fix, live verification in the running app, a commit, and a pull request.\n\nThe division of labor is simple. The arrow answers \"which element?\" The sentence answers \"what do you want done?\" Neither carries the other's job well: an arrow cannot express intent; a sentence cannot point. CleanShot's text tool collapses the two when that helps — card 3's capture carries the full design feedback as a red callout typed on the image, so the prompt shrinks to \"do what the annotation says.\"\n\nWeak version of the move: three arrows, two boxes, and a highlight on one screenshot — the agent now has five candidate subjects. Strong version: one fat arrow per idea. Two ideas, two screenshots. Crop tight.\n\n## How agents ingest the drop\n\nDifferent CLIs render a dropped image differently, but all of them get the pixels. Claude Code shows an inline `[Image #1]` marker. The Codex CLI rewrites a dragged file into a header:\n\n``` text\n# Files mentioned by the user:\n## capture.png:\n$HOME/screenshots/capture.png\n```\n\nThe difference only matters when you script prompts; drag-and-drop hides it. And the image is data, not decoration — one session opened with just a file path plus \"It is a 1612×1084 RGBA PNG. The visible symptom is…\" and the agent read the actual pixels.\n\n## What good captures look like\n\nAcross a reviewed week of ~45 captures, the annotated ones share one pattern: a single fat red arrow aimed at the one element the prompt is about — an input field, a status widget, an answer sentence. Almost never boxes or long callouts.\n\n![A Quick AI chat panel answering a World Cup schedule question, with a red arrow pointing at the empty 'Follow up…' input field at the top.](https://amber-willow-n64j.here.now/images/arrow-quick-ai-input.png)\n\nThe arrow singles out the follow-up input the prompt discussed, ignoring everything else on screen.\n\n![A terminal running Claude Code inside a coding project. A red arrow points at two small pill-shaped 'now' widgets floating in the center of an otherwise empty pane.](https://amber-willow-n64j.here.now/images/arrow-claude-code-pills.png)\n\nApplied to the agent's own UI: the arrow isolates two tiny status pills inside a busy terminal session.\n\n![A Quick AI panel showing eight web_search tool calls and an answer that begins 'I can't reliably pull today's latest news headlines from live sources right now'. A red arrow points at the answer text.](https://amber-willow-n64j.here.now/images/arrow-web-search-answer.png)\n\nFeedback aimed at agent behavior itself: the arrow marks the answer sentence under discussion, so the follow-up prompt can be one line.\n\nJudge success by the agent's first reply: it should name your arrow's target unprompted. If it misidentifies the target, don't add prose — crop tighter, keep one arrow, resend. Capture the *failure state*, not the app in general.\n\n## Check what leaves your machine\n\nScreenshots leak. The same week of captures that produced the five images on this page also contained personal message threads, a contact list with real names, a member directory, and personal photos — the same hotkey captured them all, and all of them were excluded here. An agent prompt is already a disclosure: everything visible in the frame — window titles, file paths, browser tabs, notification banners — goes to whatever service runs the model. Review the whole frame before you press send, and again, more strictly, before anything gets published. If a capture shows another person's data, re-take it rather than blurring it.\n\n## Appendix\n\n### Limits & caveats\n\n- The two real sessions are single successful runs, not controlled comparisons. No prose-only version of the same bug report was tried, so \"the arrow made the difference\" is a reasoned inference from the prompt's brevity, not a measurement.\n- The \"first reply names the arrow's target\" success test is an editorial rule of thumb, not something the sources measured.\n- The real prompts in cards 1–2 invoke the author's local slash commands (`/goal`, `/oracle-packx`, `/web-choices`) and card 5 uses a local `$image_gen` command — you won't have these. The portable versions remove them; that light generalization is the only edit.\n- The quick start and helper script assume macOS (CleanShot, `pbcopy`) and a capture folder at `~/screenshots`; set `CLEANSHOT_DIR` if CleanShot exports elsewhere.\n- Evidence is one developer's capture folder and session history over one week . It shows the workflow working; it does not measure it against alternatives.\n- Privacy exclusions, kept deliberately: personal Messages conversations, a contact list, a member-directory page, and personal photos from the same capture folder are described but never shown. Session ids and home paths are redacted in text; the five published images show only public app UIs and `~/dev`-style paths.\n- A published page is public and may be cached or indexed even if later deleted — the privacy bar for publishing is higher than for prompting.\n\n## Operating practice\n\n### Point at the visual problem\n\n#### What to notice\n\nReplace vague design prose with an **annotated image**, a bounded target, and a visible success condition.\n\n#### Try this\n\nMark the **smallest visual defect**, name what must remain unchanged, and ask for one observable correction.\n\n> “Screenshot, draw an arrow, or multiple arrows, and then paste.”\n\nJohn Lindquist · [02:18:19](https://proud-anchor-53zn.here.now/watch.html?t=8299#recording-player)\n\n#### Concept\n\nImages carry layout evidence that text often loses. Keep the request narrow: target, constraint, expected result, and one check at the viewport where the problem appears.\n\n#### Reflection\n\nAn image can show a symptom without proving its cause. Ask the agent to inspect the implementation before choosing a fix.\n\n**Recording evidence:** listen at 02:15:42.\n\n> “Please, after you're done generating the HTML, take a screenshot of the page and compare the two, so you get a diff.”\n\nJohn Lindquist · [02:21:37](https://proud-anchor-53zn.here.now/watch.html?t=8497#recording-player)\n\n[Open Prompting with Images](https://amber-willow-n64j.here.now/)\n\n#### Links shared for this topic\n\n- [Flameshot](https://flameshot.org/) — Cross-platform screenshot and annotation tooling.\n- [Shottr](https://shottr.cc/) — A macOS screenshot and annotation tool.\n\n[Watch chapter](https://proud-anchor-53zn.here.now/watch.html?t=8142#q2-annotated-image-prompt)"
}
