You spot a broken UI state on your staging build: the submit button on the checkout form overlaps the terms checkbox at narrow widths. The instinct is to write it out for Windsurf. Three sentences about where the button sits, which breakpoint, what it should do instead. By the time you finish, you have described a location the agent still has to guess at, and you have burned five minutes doing it.
A pinned screenshot with one short comment does the same job faster and lands more precisely. Here is the exact sequence, from broken screen to a link Windsurf can read.
Step 1: Capture the broken state in the browser
Open a new review in a tab. No install, no extension, no signup. Click Capture screen, and the browser asks which window or tab to share. Pick the one showing the overlapping button. The current frame gets drawn to a canvas, so what you see is what gets captured.
Outcome: you have a still of the exact state, at the exact width, where the bug appears. No reproduction steps for the agent to replay.
Step 2: Crop to the element, not the whole page
Drag a rectangle around the checkout form area. Cropping is the only image edit, and that is the point. You are not drawing red arrows or typing labels onto the picture. You are handing over the one region that matters so the agent is not scanning a full-page screenshot looking for the thing you mean.
Outcome: the item now shows a tight crop of the form with the overlap visible. A cropped still beats an annotated live page for exactly this reason, which the piece on why a cropped still wins spells out.
Step 3: Drop a numbered pin on the exact spot
Add a pin where the button edge crosses the checkbox. The pin gives Windsurf a coordinate to anchor on. Instead of "the button near the checkbox," the agent gets a numbered marker pointing at the collision. If there are two problems in the same crop, add a second pin.
Outcome: the screenshot carries a specific target. The detail on pinning a spot covers when one pin is enough and when you need more.
Step 4: Dictate the comment instead of typing a paragraph
Click into the comment and talk. In Chrome or Edge the browser's speech recognition writes it down as you speak. Say what you would say out loud: "At 375 pixels the submit button overlaps the terms checkbox. It should stack below the checkbox with 16 pixels of space." That is one sentence, spoken in eight seconds.
Notice what you did not do. You did not describe where the button is, because the pin does that. You did not describe the page, because the crop does that. The comment carries only the fix and the expected result. If you are on Firefox, type it instead. Talking through comments generally beats typing them, as the case for dictating review comments lays out.
Outcome: a short, plain instruction attached to a pinned image.
Step 5: Publish and grab the markdown link
Click Publish. The review saves and gets a short public URL at /r/<slug>. The same review is available as plain-text markdown at /r/<slug>/markdown. That markdown is the format a coding agent reads: the crop, the pin, and your comment come through as structured text, not as a screenshot the agent has to interpret.
Outcome: one link that holds the image, the target, and the instruction in a form Windsurf can parse.
Step 6: Hand the link to Windsurf
Point Windsurf at the review link and let it read the markdown. Because the feedback is already structured, the agent gets the breakpoint, the element, and the desired outcome without you rephrasing anything. The details on how markdown export works cleanly with agents live on the agent-readable feedback page.
Outcome: Windsurf edits the right element the first time, because you gave it a coordinate and a target state rather than a paragraph it has to decode.
Why this beats a written description every time
A paragraph of prose forces the agent to reconstruct the scene from your words. Was the button to the left of the checkbox or below it? Which breakpoint? What does "fix the spacing" mean in pixels? Every ambiguity is a chance for the wrong edit.
A pinned screenshot removes the reconstruction step. The image is the ground truth. The pin is the address. Your one dictated sentence is the instruction. The agent spends its effort on the fix, not on figuring out what you meant.
| You want to convey | Prose paragraph | Pinned screenshot plus comment |
|---|---|---|
| Where the bug is | A sentence describing location | A numbered pin |
| What it looks like | Your description of the render | The actual cropped still |
| What to change | Buried in the paragraph | One plain sentence |
This same flow works for any agent that reads markdown. If your team splits work across tools, the coding agents hub covers the others. Start with the checkout bug in front of you: capture it, pin it, say one sentence, publish, and paste the link.