screenshot-with-callout

# Screenshot capture sequence (mandatory at point of use)

**Invoke this skill via the Skill tool every time you are about to take a screenshot for a deliverable.** Do not rely on having read it earlier in the session. By the time you need it, the previous read is far back in your context and you will be running on vague recall. That recall is exactly what produces full-page screenshots with no callout, evidence the reviewer can't find, and clipped frames. The fix is to re-load this skill at the moment of use so the rules are adjacent to the action.

**Hard rule, before anything else:** `agent-browser screenshot file.png` with no `--selector` and no prior annotation is **forbidden** for deliverables. Raw full-viewport shots are always wrong. The only acceptable use of `agent-browser screenshot` without these prerequisites is `/tmp/debug-*.png` files for live debugging that will never be uploaded or referenced anywhere a human will see them.

## Why screenshots fail (the three reliable failure modes)

1. **The important thing is tiny.** It's one region on a busy page, surrounded by sidebar, topbar, and unrelated widgets the reviewer already knows.
2. **The important thing is cut off**: partially below the fold, sticky header covering the heading, or a dropdown clipped at the viewport edge.
3. **There's no visual indication of what to look at.** The reviewer sees a screen full of form fields and has to guess which one you mean.

A screenshot that doesn't clearly show the thing it's meant to prove is **worse than no screenshot at all**. It forces the reviewer to either trust you blindly or re-run the flow themselves. The whole point of evidence is that it's self-describing.

## Two audiences, two annotation rules

The red outline box is always welcome. The text label is the difference:

| Audience | Red outline box | Text label on the box |
|---|---|---|
| **ClickUp business reviews, bug repros, internal evidence** | Yes | **Yes**, the reviewer needs the image to self-describe |
| **End-user documentation** (`docs/docs/en/**/*.md`) | Yes | **No**, the image must not contain prose annotations |

For docs, draw a clean red outline around the element the reader should notice (no label) and explain what they're looking at in the surrounding markdown, either a `>{info}` callout or a sentence immediately above the image. End users opening the docs don't want prose burned into the image; the UI should look like what they see when they open the app, with only the visual cue pointing at the element.

For business reviews, keep the label. The ClickUp reviewer isn't reading a whole paragraph around the attachment, and they need the image to self-describe.

When in doubt, pass a label argument of `null` to the annotation helper to skip the text tag and keep only the outline.

## The capture sequence, where every step is mandatory

### Step 1. Know what you're capturing

Write the one-sentence purpose first, before touching the browser: *"the Partner Housed Configuration section with the services-only banner visible"*. If you can't say it in one sentence, you don't yet understand what the case is supposed to prove and you're not ready to shoot.

For business reviews, this should match the `evidence:` field from your Phase 4 plan (see `business-review` skill). If it doesn't match, stop and update the plan first. Improvising at capture time is how shots go wrong.

### Step 2. Scroll the target into the middle of the viewport

Use `scrollIntoView({block: "center"})`, **not** `{block: "start"}`, because `start` pins the element under the sticky topbar where it gets covered. Then verify with `getBoundingClientRect`:

```bash
agent-browser eval 'var el = document.querySelector("SELECTOR"); var r = el.getBoundingClientRect(); JSON.stringify({top:r.top,bottom:r.bottom,left:r.left,right:r.right,vh:innerHeight,vw:innerWidth,fullyVisible: r.top>=0 && r.bottom<=innerHeight && r.left>=0 && r.right<=innerWidth})'
```

If `fullyVisible` is false, either scroll differently, expand the viewport (`set viewport 1920 1400`), or crop to the element via `--selector` in step 5. **Cut-off content is a failed shot, not a done shot.**

### Step 3. Annotate: write `/tmp/annotate.js` once per session, then call it

Save the annotation helper to `/tmp/annotate.js` once at the start of your session, then call it before every screenshot. The helper draws a red outline + optional label on a fixed-position overlay that doesn't disturb the page layout:

```bash
cat > /tmp/annotate.js <<'EOF'
(sel, label) => {
  const el = document.querySelector(sel);
  if (!el) return 'no element';
  const r = el.getBoundingClientRect();
  const box = document.createElement('div');
  box.setAttribute('data-ai-callout', '1');
  Object.assign(box.style, {
    position: 'fixed',
    top: (r.top - 6) + 'px',
    left: (r.left - 6) + 'px',
    width: (r.width + 12) + 'px',
    height: (r.height + 12) + 'px',
    border: '3px solid #ef4444',
    borderRadius: '8px',
    boxShadow: '0 0 0 4px rgba(239,68,68,0.25)',
    pointerEvents: 'none',
    zIndex: '2147483647',
  });
  if (label) {
    const tag = document.createElement('div');
    tag.textContent = label;
    Object.assign(tag.style, {
      position: 'absolute',
      top: '-28px',
      left: '-3px',
      background: '#ef4444',
      color: 'white',
      font: '600 12px/1.2 system-ui, sans-serif',
      padding: '4px 8px',
      borderRadius: '6px',
      whiteSpace: 'nowrap',
    });
    box.appendChild(tag);
  }
  document.body.appendChild(box);
  return 'annotated';
}
EOF
```

Then for each screenshot:

```bash
agent-browser eval "($(cat /tmp/annotate.js))('#partner-housed-section', 'Partner Housed Configuration')"
```

Pass `null` as the second argument to omit the label (for end-user docs).

For multiple highlights on one screenshot, call the function once per element with different labels. Keep callouts focused: **1-3 per image, never a rainbow of boxes**. A callout that highlights everything