When a bug report lands as markdown, two readers open it: a developer who skims it, and sometimes an AI coding agent that parses it line by line. Both need to mean the same thing by the same words, or a fix lands on the wrong element. Four terms carry most of the weight. Here is what each one means and when it matters.
Pin
Pin: a numbered marker dropped on an exact spot of a captured screenshot, baked into the exported image so it shows in the markdown too.
A pin turns "the button is misaligned" into "pin 2 is on the Save button." The number is the anchor. When you write a comment that says "pin 2 sits 4px too low," a developer reading the image knows exactly which element you mean, and an agent reading the same still sees the marker in place. Without pins you are describing position in prose, and prose about layout is where handoffs break. Numbered pins also set a reading order, which matters when a single screenshot has three separate problems. See numbered pins that make a developer read steps in order for why the sequence is not cosmetic.
Item
Item: one unit of a review. Usually a screenshot plus its comment, but it can also be a free-floating note with no image.
The item is the thing a reader acts on. One item, one problem, one fix. If you cram two unrelated bugs into one item's comment, an agent is likely to fix one and quietly skip the other, because it reads the item as a single task. The discipline is boring but it pays off: a crop focused on the broken region, pins on the exact spots, and a comment that names the element and the expected behavior. That structure is what a markdown bug report an agent can read is built from, one item at a time. Items also map cleanly to tickets later, so a tight item list becomes a tight task list.
Why item boundaries matter for an agent
An agent works through items as a queue. Each one it can fix in a single pass is a win. Split by element, not by screen: if the header and the footer are both wrong on the same page, that is two items, even though it is one screenshot. You can reuse the image and pin different spots. The payoff shows up in the fields an LLM needs to fix feedback in one pass.
Slug
Slug: the short identifier at the end of a review's URL, the part after /r/ in /r/<slug>.
The slug is how a review is addressed. The same review is reachable several ways off that one slug: /r/<slug> for the full review, /s/<slug> for a clean read-only page, and /r/<slug>/markdown for the plain-text version an agent reads. You rarely type a slug by hand, but you will see it in links you paste into an issue or hand to a teammate. When an AI assistant opens the /r/<slug> link, it is served the markdown automatically, so the same address serves a person and an agent without you doing anything different. That is the quiet advantage of markdown screenshots: one link, two readers.
Resolved
Resolved: a state the review owner sets on an individual comment, marking that the point has been handled.
Anyone with the review link can comment on any item. The owner reads those comments and marks each one resolved when it is done. This is not a workflow engine with assignees and columns. It is a single resolved flag per comment, enough to track what is closed and what is still open without standing up a bug tracker. If you have been reaching for status columns here, the lighter model is covered in resolving comments without a bug tracker. For an agent, resolved is a signal too: a comment marked resolved is one it can skip on the next pass.
How the four fit together
A review has a slug. The review holds items. An item carries a screenshot with pins and a comment. Comments get marked resolved. Say "item 3, pin 1" and both a developer and an agent land on the same pixel. Keep items to one problem each and resolved stays meaningful instead of blurry.
One caution on agent input: the markdown carries references to the exported images, and the pins live inside those images. An agent that only reads the text and never opens the still will miss what the pin points at. The fix is to make sure the agent reads the screenshot, which is the whole reason the markup is baked into the image rather than drawn on a live page. More on that in why your agent should read the screenshot, not a link.
If you want these terms in front of you while you work, start a review, drop a pin, write one item, and publish it to get the slug. Free to try with no password or card; a review stays editable for 7 days, and the $5 Pro plan removes that cutoff if you need to keep editing longer.