Prove It

You are the quality-control step. A change has been made — a feature, a fix, a perf improvement — and someone is about to trust a sentence like "tested, works". Your job is to replace that sentence with evidence: for each named claim, a captured result from a real browser, and a verdict of pass, fail, or not-exercised. If anything is not pass, the change goes back to build. You do not summarise, soften, or open the PR on a non-pass.

Two things this skill is not: it is not a UX review (no opinions, no fix list — that is ux-audit), and it is not "have a look at the page" (that is web-browse). It needs a change under test and claims about it.

Inputs

• Test targets (required). One or more behaviours phrased as testable statements: "the coupon field rejects expired codes", "the dashboard loads in under 300 ms", "the empty state shows the import CTA". If the user gives none, derive them from the diff or PR title, list them back, and proceed. Out of scope for this skill: anything the browser session cannot observe — a downloaded file's contents, an email that was sent, a row written to a database. Say so and prove it another way (a script, a query) rather than passing a target a screenshot cannot support.
• Revision under test: git rev-parse --short HEAD and the branch, or the deployment URL. It goes in the report header.
• Where to post (optional): a PR or issue number for gh.

Step 0 — Doctor, then choose a mode

thinkrun doctor

Read three lines of the output before anything else:

• Server acceptance: accepted — an API key is accepted. The Activity Feed session, the share link, and cloud mode all depend on this. Without it, local mode still works and the report says session: none (no API key).
• Bridge health — the extension + native host are up; local mode is available.
• If neither local nor cloud is available, stop and paste the doctor output. Do not fall back to "I verified by reading the code". That is the failure this skill exists to prevent.

Local mode — the app needs the user's login or cookies, or runs on localhost.

thinkrun tabs
TAB_ID=<a clean tab from the list>
thinkrun attach $TAB_ID --audit      # --audit: best-effort screenshot after each state change

Pin the target on every command. The CLI's "active tab" is machine-wide state; another agent or terminal attaching a different tab moves it under you, and your captures land in a different session than the one you share. Set one variable and use it everywhere below:

T="--tab $TAB_ID"      # local mode
trap 'thinkrun audit off --tab '"$TAB_ID"' >/dev/null 2>&1' EXIT   # audit mode never outlives this run, even on abort

Cloud mode — no display, no extension, or a public URL. The cloud browser cannot reach your machine's localhost: a localhost target needs local mode, or a tunnel (ngrok, cloudflared) and the tunnel URL as $URL. (Command surface verified against CLI 0.1.37; the end-to-end cloud path was not smoke-tested when this skill shipped — a session-provisioning incident on 2026-09-18.)

SID=$(thinkrun cloud start --json | jq -er .data.sessionId) || { echo "cloud start failed"; exit 1; }   # needs an accepted API key
T="--mode cloud"        # cloud mode: no --tab; commands run against the active cloud session
trap 'thinkrun cloud stop -s "$SID" >/dev/null 2>&1' EXIT   # stops THIS session by id, never whatever is active
# the active cloud session is also machine-wide state (`cloud use`, another `cloud start`).
# There is no per-command session flag, so assert it before every target's captures:
same_session() { [ "$(thinkrun cloud status --json | jq -r .data.sessionId)" = "$SID" ] || { echo "active cloud session changed; stop"; exit 1; }; }

If the target is on localhost (local mode only), confirm the port answers your process before capturing anything — another service may be squatting it. In cloud mode, confirm reachability from the cloud browser instead: thinkrun navigate "$URL" $T and check the returned title.

PORT=<port>; lsof -iTCP:$PORT -sTCP:LISTEN | head -3; curl -sI http://localhost:$PORT | head -1

Set up the evidence folder (gitignored — evidence is posted, never committed):

TASK=<short-slug>; mkdir -p .artifacts/$TASK
REV="$(git rev-parse --short HEAD) $(git branch --show-current)"

Step 1 — Before state (fixes only)

If a target is a bug fix, capture the failure before applying the fix. It is the cheapest moment to prove the bug existed, and the after-shot means nothing without it.

The before capture must come from the pre-fix build: the previous deployment URL, or the base revision in a separate worktree (git worktree add /tmp/before origin/main and run it on another port) — never by stashing or checking out over the user's working tree. Capturing the current (fixed) build and calling it "before" is mislabelled evidence. If no pre-fix build is reachable, write before: unavailable in the report — do not fabricate one.

BEFORE_URL=<the pre-fix build — e.g. http://localhost:4001 for the base worktree, or the previous deploy>
thinkrun clear-logs $T
thinkrun navigate "$BEFORE_URL" $T; sleep 2
# perform the SAME interaction the target describes (fill, click, …) — a screenshot of
# the untouched page is not evidence of the bug; the failure has to be on screen
thinkrun screenshot --output .artifacts/$TASK/before-01-<target-slug>.png --caption "before: <target>" $T
thinkrun console --json $T | jq '.data.logs' > .artifacts/$TASK/before-01-console.json
thinkrun network --json $T | jq '.data.requests' > .artifacts/$TASK/before-01-network.json

Step 2 — One pass per target

For each target, in order:

1. Navigate to the starting state (logged in, right page). Setup is not evidence unless setup is the target.
2. Bound the window: thinkrun clear-logs $T — console and network buffers are cumulative; without this, an earlier target's error or request gets attributed to this one. In cloud mode run same_session first.
3. Perform the interaction: thinkrun click, fill, type, press, select, scroll — each with $T.
4. Wait for the state the target names. A capture taken the instant after a click records the page mid-flight: the request has not landed, the message has not rendered, and you get a false fail — or a false pass from the previous state. Pick the condition from the target itself:

   thinkrun wait-for-text "This code has expired" $T        # the text the target names
   thinkrun wait "<css-that-appears>" $T                    # or the element
   # or poll until the expected request reaches a terminal status:
   deadline=$((SECONDS+15))
   until thinkrun network --json $T | jq -e '[.data.requests[] | select(.url|test("/api/coupons")) | select(.status != null)] | length > 0' >/dev/null; do
     [ $SECONDS -lt $deadline ] || { echo "request never reached a terminal status"; break; }   # -> not-exercised
     sleep 0.3
   done

   A bare sleep is a last resort; if you use one, say so in the Evidence cell.
5. Capture — this is the evidence, not the audit-mode screenshot:

   N=01; SLUG=<target-slug>
   thinkrun screenshot --output .artifacts/$TASK/$N-$SLUG.png --caption "$N $SLUG" $T
   thinkrun console --json $T | jq '.data.logs' > .artifacts/$TASK/$N-$SLUG-console.json
   thinkrun network --json $T | jq '.data.requests' > .artifacts/$TASK/$N-$SLUG-network.json
   # console entries are {level, message, args, timestamp}; requests are {url, method, status, duration, startTime, endTime}
   jq '[.[] | select(.level=="error") | .message]' .artifacts/$TASK/$N-$SLUG-console.json

   --caption is what syncs a local screenshot into the Activity Feed session (as a screenshot action); without it the file is local only.
6. Look at the screenshot with the Read tool. Check the console for errors and the network list for failed or slow requests — after step 2, everything in the buffers belongs to this target.
7. If click returns "category": "no_op_click", the click did not change page state. That is evidence. Record it against the target; do not reach for thinkrun evaluate to call the handler directly and then call the button "working".
8. Record the verdict and the reason:
   • pass — the statement holds and the capture shows it.
   • fail — the statement does not hold. Say what happened instead.
   • not-exercised — you could not reach the state (blocked login, missing fixture, flaky page). This is not a pass and blocks the same way.

Audit mode (--audit) attempts an extra screenshot after state-changing actions so the Activity Feed shows a trail. Treat it as a convenience for the reviewer's timeline; the named captures above are the record.

Non-visual targets

Performance, API, and CLI claims get numbers or output pairs, not screenshots of a terminal.

# page load (ms) — the navigation entry, not an individual request
thinkrun clear-logs $T; thinkrun navigate "$URL" $T; sleep 2
thinkrun evaluate "Math.round(performance.getEntriesByType('navigation')[0].duration)" $T
# a specific request's duration (ms) — only when the target names that request
thinkrun network --json $T | jq '[.data.requests[] | select(.url|test("/api/dashboard")) | {url, status, ms: .duration}]'
# a value from the page
thinkrun evaluate "document.querySelectorAll('table tbody tr').length" $T

State which of these the target means. "Loads in < 300 ms" is the navigation entry; "the dashboard request returns in < 300 ms" is that request's duration.

Record the measured value and the threshold: 615 ms → 61 ms (target < 300 ms). For a perf fix the before measurement comes from Step 1.

Step 3 — Write the report

.artifacts/$TASK/report.md, from references/report-template.md. The table is the product; every Evidence cell is a file path or a share-link step, never a sentence.

| # | Target | Result | Evidence |
|---|--------|--------|----------|
| 1 | coupon field rejects expired codes | pass | 01-coupon-expired.png; console clean; POST /api/coupons 422 |
| 2 | dashboard loads in < 300 ms | fail | 02-dashboard-network.json: 615 ms |
| 3 | export downloads a 3-column CSV | not-exercised | export button disabled on staging (no data fixture) |

Session line. With an accepted API key, the session is recorded to the Activity Feed. The page for it is owner-only; a reviewer needs a share.

A share of a session recorded on a logged-in tab can expose the user's authenticated pages, API responses, console output and request details to anyone with the link. So:

• Ask before sharing. Never create a share without the user's explicit yes for this run. Default is session: not shared.
• Password-protect it by default (password in the request). Choose the password yourself, never echo it, and give it to the user in your reply to them — never in the report, the PR, a commit, or shell output. Without that handoff the link is unusable, so do it in the same message as the link.
• Leave console and network out of the share unless the user asks (includeConsoleLogs / includeNetworkRequests default false here); the per-target JSON files already hold that evidence locally.
• Prefer a test account and non-production data for anything that will be shared.

With the user's yes:

CFG=$(thinkrun config show | sed -n 's/^Config file: //p'); CFG=${CFG:-$HOME/.config/thinkrun/config.json}
API=$(jq -r .apiUrl "$CFG")
# local mode: the Activity Feed session for the tab you pinned (NOT the id from `session debug`)
[ "$T" = "--mode cloud" ] || SID=$(jq -r .sessionId ~/.thinkrun/local-session-$TAB_ID.json)
# cloud mode: SID is the one you captured in Step 0; if lost, `thinkrun cloud status --json | jq -r .data.sessionId`
# never start a new cloud session here — it would be empty

# Secrets never appear in any command's arguments (shell history, transcripts, `ps`):
# the API key is read from the config FILE by jq, the password is a FILE you write
# with your file tool, and both reach curl through 0600 files. Fail closed.
umask 077; SEC=".artifacts/$TASK/.share"; mkdir -p "$SEC"
#   <file tool>: write "$SEC/pw" containing the password you chose, then:
[ -s "$SEC/pw" ] || { echo "no password — not sharing"; TOKEN=""; }
if [ -s "$SEC/pw" ]; then
  jq -n --rawfile pw "$SEC/pw" --arg sid "$SID" \
    '{sourceType:"session", sourceId:$sid, password:($pw|rtrimstr("\n")), includeConsoleLogs:false, includeNetworkRequests:false}' > "$SEC/body.json"
  jq -r --slurpfile cfg "$CFG" -n '"header = \"x-api-key: \($cfg[0].apiKey)\"", "header = \"content-type: application/json\""' > "$SEC/curl.conf"
  printf 'data = "@%s"\n' "$SEC/body.json" >> "$SEC/curl.conf"
  TOKEN=$(curl -sf -K "$SEC/curl.conf" -X POST "$API/api/share" | jq -er '.token // empty') \
    || { echo "share creation failed — report 'session: not shared', do not post a link"; TOKEN=""; }
fi
rm -rf "$SEC"
[ -n "$TOKEN" ] && echo "session: https://thinkrun.ai/s/$TOKEN (password-protected)"

Before pasting the link, confirm your captures are in it — the share is only evidence if it contains your steps:

curl -s "$API/api/share/$TOKEN/meta" | jq '[.data.actions[] | select(.type=="screenshot") | .details.caption]'
# (public endpoint, no key needed) expect your "01 …", "02 …" captions; if missing, you shared the wrong session

Key handling. $KEY is the user's durable API key. It is read once, sent to curl on stdin (never in argv), and used for that one request. Do not print it, do not put it in the report, the PR, or a log line. If the harness records shell output, prefer a short-lived key for this step.

Write exactly one of: session: https://thinkrun.ai/s/<token> (password-protected), session: not shared, or session: none (no API key). Never paste /sessions/<id> — it is a login wall. Images are inlined or attached regardless; the share is supplementary.

In cloud mode, thinkrun cloud artifacts lists the session's screenshots with presigned URLs; there is no equivalent for local sessions, so the named captures are the record there.

Step 4 — The rule

If any row is fail or not-exercised, clean up first — thinkrun audit off $T (local) or thinkrun cloud stop -s "$SID" (cloud) — so nothing keeps capturing or billing, then end with:

Back to build. Rows N, M did not pass. Fix, then run /prove-it again for those targets. Do not open or update the PR with this report as "tested".

That sentence is the last thing you write. Not a summary, not "mostly works", not the PR. If every row is pass, continue.

Step 5 — Post

Only post evidence a reviewer can open. .artifacts/ is gitignored, so a report whose Evidence cells are local paths proves nothing to anyone but you. Before commenting, check what the reviewer will be able to see:

• Share created (the user said yes) → the captures are in the session timeline; post the report with the link.
• No share → do not post the table to the PR as proof. Give the report and the file paths to the user in your reply and say what to attach. If they want something on the PR now, post a short comment that names the targets and their results and states that the captures are local and pending attachment — never a table of paths nobody can open.

gh pr comment <n> --body-file .artifacts/$TASK/report.md      # only when the evidence is reachable
gh issue comment <n> --body-file .artifacts/$TASK/report.md   # when the destination is an issue

gh cannot attach images from the CLI. The screenshots reach the reviewer through the share link (they are in the session timeline). When there is no API key and therefore no share, say so in the comment and leave the PNGs in .artifacts/$TASK/ for the human to drag into the PR. Never upload evidence to a third-party paste host.

Clean up: thinkrun audit off $T (local); the cloud trap stops $SID by id.

What this skill does not claim

• Local mode produces per-step captures, not a video. Do not call it a recording.
• thinkrun cloud artifacts exists for cloud sessions only.
• ThinkRun does not judge the claims. The pass / fail in the table is your adjudication, backed by the captures. Say so if asked.
• The --audit screenshot is best-effort. If it is missing for a step, the named capture you took is still the evidence.
• Cloud mode has no per-command session flag; same_session checks the active session before each target, and another process can still switch it between that check and a capture. Local mode with --tab has no such gap.
• The localhost check confirms a listener answers on the port, not that it is the exact process for the revision under test; if that matters, expose a build id on the app and read it before capturing.
• A share is revocable (DELETE /api/share/<token> with the key), not secret-for-life; revoke it when the PR merges.

Do NOT use for

• "Walk through the app and tell me what's confusing / broken" → ux-audit
• "Go check whether the pricing page loads" (no change under test) → web-browse
• "Use the thinkrun CLI to click X" / "use the ThinkRun MCP tools" → thinkbrowse-cli / thinkbrowse-mcp
• Writing Jest / Playwright / Cypress tests
• Reading the diff and reasoning about whether it should work