Point your agent at this page and a capture folder, such as ~/Documents/Jot/Captures/latest, and ask for feedback you can send. It makes one web page, or a PDF if you ask.

Cleaning up a capture into feedback

For an agent, such as Claude Code, that a person has pointed at a Jot capture.

A capture is someone talking through a few screens and scribbling on them as they go: filler words, swearing, half-finished thoughts, a fat wobbly loop round a button. Your job is to turn it into feedback they can send to a colleague as it is, with their drawings redrawn neatly over clean screenshots, in one web page or PDF.

What the folder holds

A capture is a folder in Captures/, named for when it started, such as 20261103_101200. Read recording.xml first. It holds everything you need in time order. status="finished" says the person has stopped; while it says recording, they’re still going.

<context/>
<timeline>
  <speech source="mic" predicted_speaker="mic.a" start="24.7" end="33.1">And then down here, mark two, why is it showing me the whole bloody path…</speech>
  <shot source="screen" start="33.6" file="shots/01.png" clean="shots/01-clean.png" drawing="shots/01.svg">
    <ink id="ink-1" tool="highlighter" shape="loop" box="0.232 0.513 0.717 0.653"/>
    <ink id="ink-3" tool="highlighter" shape="underline" box="0.274 0.821 0.825 0.832"/>
    <mark number="1" x="0.698" y="0.548"/>
    <mark number="2" x="0.850" y="0.809"/>
  </shot>

context holds anything known from outside, such as a note the person typed. It is often empty.
speech is what the person said, as heard. Times are seconds from the start.
shot is a screenshot. It owns the words said since the shot before it. People talk first and snap when they’ve finished, so the words just above a shot are about that shot. A caption, when there is one, is what the person called it.
file is the picture as the person saw it, drawing and all.
clean is the same screen with nothing drawn. Draw on this one.
ink is one thing drawn. tool is highlighter, box, arrow or number; a highlighter stroke also has shape, Jot’s guess at what it is. box is its extent as fractions of the width and height, left, top, right, bottom; an arrow has from and to, the tail and the tip. A freehand arrow’s head is a second ink with shape="arrowhead" and part_of naming the arrow.
mark is a numbered disc the person placed. When they say “mark two”, this is what they mean. Ids count every drawing in order, numbers included, so ink-1 then ink-3 means the second thing drawn was a number, listed as a mark.

When the shape guess looks wrong, trust the picture and the words. shots/01.svg draws each ink as a group with the same id, its viewBox the picture’s size in pixels. events.jsonl keeps each stroke’s points in pixels, its width, color and opacity, a freehand arrow’s tip, and the picture’s width and height, should you want them. You won’t need settings.toml or audio/.

What good feedback looks like

The reader, a colleague who wasn’t there or their agent, wants to know quickly what to change, why, and where:

A title and a short summary. The title names what was reviewed and claims nothing the person didn’t say. Then a sentence of context and the three to five changes that matter most, as bullets, most important first, so a reader who stops here knows what to do. With three points or fewer, one sentence naming them is enough, so the page doesn’t say everything twice. Remarks about the whole capture, such as “overall, really good”, go here wherever they fall, often just before the last shot. With no such remark, don’t add one.
Each screen in turn, in the order of the capture: a short heading that names the screen, the redrawn picture, then the points about it.

Importance is the person’s: what they said matters most, what stopped them, or what they felt most strongly about.

A screen’s points

Number the points that ask for a change and have a drawing, 1 to n across the document with no gaps, each with a matching disc, so point 4 is found by looking for disc 4. The person’s own mark numbers don’t carry over.

One remark with two drawings is one point, with its disc on the drawing on the thing the change is about.
A point with no drawing follows the numbered ones as a plain bullet.
A waved-away point with a drawing (“not a huge deal”) keeps its number, opens with “A small one:”, and stays out of the summary.
A mixed remark (“I like it but it’s tiny”) is a change point, with the praise in the same line.
What’s working comes last, when the person praised something here, since it tells a team what to keep. Drawings on praised things stay off the picture, where they’d read as something to fix. A reaction too thin to read, such as “Yes.”, is left out.

How to say it

Candid and professional, in the first person, since it goes out under the person’s name. Say what the problem is and what it does to someone using the screen, then stop, as a respected senior colleague would: honest about the problem, kind to whoever built it. Keep the evidence; drop the filler, swearing and venting.

They said	The feedback says
“This bit is shit, I don’t get what’s going on here, the colours are all off”	“This screen is hard to follow, and its colours don’t match the rest of the app.”
“I have no idea what this Input Monitoring thing is saying, nobody’s going to read that”	“The Input Monitoring description is hard to follow. I read it three times and still wasn’t sure what it allows; most people won’t read that far.”

Keep the person’s meaning, and only theirs. Don’t add problems they didn’t raise, even ones you can see; mention those in your reply, outside the file.

When the person changes their mind, go with where they ended up and drop the abandoned view, along with its mark. A mark left from a withdrawn point is dropped even when it sits beside a live one. A decision they repeat (“no, move it up. Move it up.”) is settled. Keep the doubt only when they never settle: “move it up, or maybe it’s fine, I don’t know” becomes “I’d consider moving this up, though I’m not sure”.

A complaint withdrawn into “keep it” is praise, and goes under What’s working, as does a default they said is right. Any middle step drops too: “get rid of it”, then “maybe just smaller”, then “keep it, it’s fine” is only praise.

Suggestions are theirs too. Include the fix they suggested, or both if they offered two. When they only named a problem, leave it as a problem: the team may have a better fix.

Redrawing the annotations

Use the ink only to find what the person meant, then draw on the thing the problem is about, snapped to its edges: a scribble over the end of a hint, from someone talking about “the hint”, becomes a rectangle round the whole hint. Every numbered point gets a disc, whether or not the person placed one.

The person drew	Redraw it as	Where its disc goes
A `loop` or `box`	A rounded rectangle round it.	Just outside a corner on the side the person put it, else the top-left.
An `underline`	A straight, level line under the named text, first character to last.	At its left end, just above or below the line; in tight text, past the right end of the line; failing that, over the left end at 18 px.
An `arrow` or `line`	A straight line; an arrow gets a solid triangular head, stopping just short of its target.	At the tail. Never at the tip.
A `scribble`	Usually it just means “this”: a rectangle, as for a loop.	As for a box.

Anything the person wants removed or cut down gets a dashed rectangle, whatever they drew, and the text uses their own verb: “remove” for remove, “cut down to one line” for cutting down. A “move this” arrow can be redrawn in clear space beside the rows it crosses.

Sizes, as they look on the page, where a picture usually shows about 680 px wide: lines about 3 px with a halo about 2 px wider on each side; discs about 24 px across with a white bold 14 px number; arrowheads about 12 px long and 10 px across; corners about 4 px round, with 4 to 6 px between the halo’s outer edge and what they surround. To convert to the picture’s pixels, multiply by its width over its shown width: for a 2000 pixel screenshot, about 2.9, so lines about 9 pixels and discs about 70 with a 41 pixel number.

Colour: Jot’s brush blue, #2F4BFF, for every mark and disc, so the tidy picture looks like Jot’s own, each on a halo of the screen’s nearby background colour at 85% opacity, so it reads on light and dark screens. No words go on the picture; the list carries them.

When rules collide. Keeping a disc clear of the thing marked, and inside the picture, beats any placement rule: when the person’s side is crowded, use the nearest clear side. Where there is no clear side, the disc can shrink to 18 px on the page. Text stays readable before a mark keeps its size, so between tight lines of text, thin the halo or the line. The person’s meaning comes before the house style.

Building the file

A web page is the default: one .html file with each clean picture embedded as a data: URI and the marks as inline SVG over it, its viewBox the picture’s size in pixels, so it works as an attachment. Keep it plain: a system font, a column about 70 characters wide, pictures at its full width.

<figure class="shot">
  <img src="data:image/png;base64,…" alt="The Permissions screen">
  <svg viewBox="0 0 2000 1360" aria-hidden="true">…the redrawn marks…</svg>
</figure>
<style>
  .shot { position: relative; margin: 0; }
  .shot img { display: block; width: 100%; height: auto; }
  .shot svg { position: absolute; inset: 0; width: 100%; height: 100%; }
</style>

A PDF is easiest made from the page with Chrome’s --print-to-pdf, with break-inside: avoid on each section.

Save the file where the person asks, or else in the folder that holds the capture folder (a file inside it is easy to lose), named for what it reviews, such as permissions-feedback.html.

Checking it

Look at the page as the reader will, on a Mac with:

"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --headless=new --disable-gpu \
  --user-data-dir="$(mktemp -d)" --window-size=1200,3000 \
  --screenshot=page.png "file:///absolute/path/feedback.html"

Elsewhere, use google-chrome or chromium, then look at page.png. With no browser, drawing the marks with an image library will do.

The marks read and land: each disc’s number is easy to read, no mark covers what it points at, and each shape sits on the same thing as in the person’s file.
The numbers match, 1 to n with no gaps, each with its disc.
Every point is there, or left out for a reason, and nothing is added.
The writing reads well aloud. Each summary line and point says the problem and its effect, keeps the person’s meaning, and sounds like a colleague.
The summary matches the sections.
It stands alone: no src="http or href="http. An SVG’s xmlns loads nothing.

Then tell the person where the file is and what you were unsure of. If a screenshot shows something private, such as a username in a file path, point it out and leave the picture alone; it’s their call.

A worked example

This example is invented. A person reviewing the checkout of a garden-planning app said, before their only shot:

Um, okay, so this is the checkout. This button, mark one, it’s grey, I literally thought it was disabled, like, what the hell. I sat there waiting. The price breakdown, love that, really clear. Oh and the delivery date, mark two, it’s tiny, but whatever, not a big deal. Actually no, it is a big deal, that’s what people care about. And the coupon thing, mark three, get rid of it. Hmm, no, leave it, it’s fine. It’s this gift message box, I’ve no idea if it’s printed on the card or what. Oh, and the page took ages to load. Overall though, pretty nice.

They drew a loop round the button with mark 1 at its top right, an underline under the price breakdown, an underline under the date with mark 2 at its right end, a loop round the coupon field with mark 3, and a loop round the gift message box.

The feedback:

Checkout

I went through the checkout once. Overall it’s pretty nice. Three changes would help:

Make the Place order button look active. It’s grey, and I took it for disabled.

Make the delivery date easier to see. It’s what people look for, and it’s very small.

Say what happens to the gift message.

Checkout

[the clean screenshot: a rectangle round Place order with disc 1 at its top right, where the person put it; a line under the delivery date with disc 2 at its left end; a rectangle round the gift message box with disc 3 at its top left]

The Place order button is grey, so I took it for disabled and waited for it to change. It needs to look like something to press.

The delivery date is too small. It’s what people care about here, so it should stand out.

I couldn’t tell what happens to the gift message. Is it printed on the card?

The page took a long time to load.

What’s working: the price breakdown is clear.

What changed, and why:

“What the hell” went; “I sat there waiting” stayed, as evidence.
The person settled on the date mattering, so it’s in the summary.
Mark 3 served a withdrawn point, so it’s gone, and the gift message box is point 3.
The praised breakdown lost its underline; the slow load, with no drawing, is a bullet.
A hard-to-read terms link is left out, because the person didn’t mention it.

A worked example of the picture

These invented cases are the awkward ones.

One remark, two drawings. “This box is empty, I didn’t know what to type, the hint’s way up there in grey, mark four.” They drew an arrow into the empty search box and a loop with disc 4 round the hint. The change is about the box, so disc 4 moves to the arrow’s tail, and the hint keeps a rectangle with no disc.
An underline in tight text. The person underlined a plant’s Latin name, with a heading just above and more text just below. With no room for a disc above or below, it sits just past the line’s right end; had there been text there too, it would sit over the left end at 18 px, with the halo thinned so no text is covered.
A loop round something to remove. “The ad banner, honestly I’d lose it”, with a loop round it. The meaning is “remove”, so it becomes a dashed rectangle.
An unmarked drawing. “And make the add button bigger”, with an arrow and no mark. It asks for a change and has a drawing, so it takes the next number, with a disc at the arrow’s tail.