Argos PR Review
Argos is a visual testing platform: each CI build captures screenshots and
compares them to a baseline, producing per-snapshot diffs. A build with
changes-detected is waiting for a human (or you) to decide whether each change
is intentional, a regression, or a flaky capture.
Treat the Argos build as one input to the PR review, never the sole source of
truth. Infer the intended UI change from the PR title, description, linked issue,
and code diff first, then use Argos to confirm the rendered result matches.
Tooling & auth
Drive Argos through the argos CLI — load the argos-cli skill for the token
model and flags. In short: build get / build snapshots need a project token
(ARGOS_TOKEN/--token); submitting a review or comment needs a personal
access token (--token / argos login). Always use --json when parsing, and
never print token values. If no PAT is available, give the user your conclusion
and evidence instead of posting — the CLI can't submit the review.
Workflow
Inspect the build — argos build get <ref> --json. Decide from status:
| Status |
Meaning / next step |
accepted / no-changes |
Already approved / no visual diff — no review needed |
pending / progress |
Not ready — stop and report it can't be reviewed yet |
changes-detected |
Needs a decision — fetch snapshots |
rejected / error / aborted/ expired |
Don't approve until the cause is understood |
Fetch what changed — argos build snapshots <ref> --needs-review --json.
For each diff inspect url (diff mask), base.url (before), head.url
(after), and head.metadata, plus the flakiness signals test.metrics and,
on a change, change.occurrences / change.ignored (used in step 3).
Judge each diff against the inferred intent:
Intentional — matches the code change and renders cleanly.
Regression — broken layout/overlap, clipping, wrong state/theme/route,
missing content, or a removed snapshot with no matching test removal.
Flaky — weigh two independent signals; when they agree, call it flaky
with confidence:
- Test history —
test.metrics.flakiness (0 stable → 1 flaky) and
change.occurrences (how many times this exact diff has recurred over
the metrics period). A high flakiness score or a recurring change is strong
evidence the diff is environmental noise, not this PR's work; stability
(builds without a change), consistency (do changes repeat identically),
and uniqueChanges explain why it scores that way. change.ignored: true
is already known-flaky and auto-approved — never read it as a regression.
- This capture — a spinner/skeleton, async content not yet loaded,
mid-animation, drifting dynamic values,
head.metadata.test.retry > 0, or
identical score/head.url across browsers (both captured the same
transient state). retries (the configured budget) is not itself a signal.
Conversely, a stable test (flakiness→0, high stability, a first-time
change) that changed is more likely intentional or a real regression — don't
dismiss it as flaky on the visuals alone. Tune the window with
build snapshots --metrics-period <24h|3d|7d|30d|90d> (default 7d).
Comment on specific diffs — the highest-value output of an agent review.
A binary approve/reject is cheap; specific, anchored feedback is what makes an
agent review worth reading. For each problem diff, post a comment that names
what's wrong and how to fix it, anchored to that snapshot:
argos comment create <ref> --token <pat> --diff <screenshotDiffId> \
--body "Loader still visible — capture runs before data loads. Wait for settled content (or mark the loader aria-busy)."
<screenshotDiffId> is the diff id from build snapshots --json.
- Pin to a region with
--anchor-lines <from,to> or --anchor-point <x,y>
(normalized 0–1); reply in a thread with --reply-to <commentId>.
- Use
--draft to bundle comments into your pending review, then submit them
together in the next step.
Submit the review (or report if no PAT is available):
- Approve:
argos review create <ref> --token <pat> --event approve
- Request changes:
argos review create <ref> --token <pat> --event reject --body "<summary>"
- Neutral note only:
--event comment --body "<summary>"
- Add
--project owner/project for build-number refs (not URLs).
- Silence a confirmed recurring flake so it stops blocking future builds:
argos change ignore <change.id> --token <pat> --project owner/project
(reverse with change unignore). Only ignore flakes the metrics confirm —
never to bypass a real diff; prefer a code fix
(references/flaky-fixes.md) when one exists.
- Lead with the inferred intent, the snapshots reviewed, and the evidence. In
the PR, cite the build URL and affected snapshot names; for flakes, name the
signal and recommend a fix.
References
- references/baseline.md — baseline selection and
orphan-build semantics (load when the review depends on which baseline was used).
- references/flaky-fixes.md — concrete code fixes for
flaky captures (
aria-busy, data-visual-test, animation stabilization).
1---
2name: argos-pr-review
3description: >
4 Review Argos visual regression builds as one input to a pull request review.
5 Use when a PR has an Argos build link, an Argos status check, or a bot comment
6 pointing to an Argos build, and you need to decide whether the visual diffs
7 match the developer's intent before approving.
8metadata:
9 source: https://skillmd.com/skills/argos-ci/argos-pr-review
10---
11
12# Argos PR Review
13
14**Argos** is a visual testing platform: each CI build captures screenshots and
15compares them to a baseline, producing per-snapshot **diffs**. A build with
16`changes-detected` is waiting for a human (or you) to decide whether each change
17is intentional, a regression, or a flaky capture.
18
19Treat the Argos build as **one input** to the PR review, never the sole source of
20truth. Infer the intended UI change from the PR title, description, linked issue,
21and code diff _first_, then use Argos to confirm the rendered result matches.
22
23## Tooling & auth
24
25Drive Argos through the `argos` CLI — load the **argos-cli** skill for the token
26model and flags. In short: `build get` / `build snapshots` need a project token
27(`ARGOS_TOKEN`/`--token`); submitting a review or comment needs a **personal
28access token** (`--token` / `argos login`). Always use `--json` when parsing, and
29never print token values. If no PAT is available, give the user your conclusion
30and evidence instead of posting — the CLI can't submit the review.
31
32## Workflow
33
341. **Inspect the build** — `argos build get <ref> --json`. Decide from status:
35
36 | Status | Meaning / next step |
37 | ------------------------------------------- | ---------------------------------------------------- |
38 | `accepted` / `no-changes` | Already approved / no visual diff — no review needed |
39 | `pending` / `progress` | Not ready — stop and report it can't be reviewed yet |
40 | `changes-detected` | Needs a decision — fetch snapshots |
41 | `rejected` / `error` / `aborted`/ `expired` | Don't approve until the cause is understood |
42
432. **Fetch what changed** — `argos build snapshots <ref> --needs-review --json`.
44 For each diff inspect `url` (diff mask), `base.url` (before), `head.url`
45 (after), and `head.metadata`, plus the flakiness signals `test.metrics` and,
46 on a change, `change.occurrences` / `change.ignored` (used in step 3).
47
483. **Judge each diff** against the inferred intent:
49 - **Intentional** — matches the code change and renders cleanly.
50 - **Regression** — broken layout/overlap, clipping, wrong state/theme/route,
51 missing content, or a removed snapshot with no matching test removal.
52 - **Flaky** — weigh two independent signals; when they agree, call it flaky
53 with confidence:
54 - _Test history_ — `test.metrics.flakiness` (0 stable → 1 flaky) and
55 `change.occurrences` (how many times this **exact** diff has recurred over
56 the metrics period). A high flakiness score or a recurring change is strong
57 evidence the diff is environmental noise, not this PR's work; `stability`
58 (builds without a change), `consistency` (do changes repeat identically),
59 and `uniqueChanges` explain _why_ it scores that way. `change.ignored: true`
60 is already known-flaky and auto-approved — never read it as a regression.
61 - _This capture_ — a spinner/skeleton, async content not yet loaded,
62 mid-animation, drifting dynamic values, `head.metadata.test.retry > 0`, or
63 identical `score`/`head.url` across browsers (both captured the same
64 transient state). `retries` (the configured budget) is not itself a signal.
65
66 Conversely, a **stable** test (`flakiness`→0, high `stability`, a first-time
67 change) that changed is more likely intentional or a real regression — don't
68 dismiss it as flaky on the visuals alone. Tune the window with
69 `build snapshots --metrics-period <24h|3d|7d|30d|90d>` (default `7d`).
70
714. **Comment on specific diffs — the highest-value output of an agent review.**
72 A binary approve/reject is cheap; specific, anchored feedback is what makes an
73 agent review worth reading. For each problem diff, post a comment that names
74 what's wrong and how to fix it, anchored to that snapshot:
75
76 ```bash
77 argos comment create <ref> --token <pat> --diff <screenshotDiffId> \
78 --body "Loader still visible — capture runs before data loads. Wait for settled content (or mark the loader aria-busy)."
79 ```
80
81 - `<screenshotDiffId>` is the diff `id` from `build snapshots --json`.
82 - Pin to a region with `--anchor-lines <from,to>` or `--anchor-point <x,y>`
83 (normalized 0–1); reply in a thread with `--reply-to <commentId>`.
84 - Use `--draft` to bundle comments into your pending review, then submit them
85 together in the next step.
86
875. **Submit the review** (or report if no PAT is available):
88 - Approve: `argos review create <ref> --token <pat> --event approve`
89 - Request changes: `argos review create <ref> --token <pat> --event reject --body "<summary>"`
90 - Neutral note only: `--event comment --body "<summary>"`
91 - Add `--project owner/project` for build-number refs (not URLs).
92 - Silence a **confirmed recurring** flake so it stops blocking future builds:
93 `argos change ignore <change.id> --token <pat> --project owner/project`
94 (reverse with `change unignore`). Only ignore flakes the metrics confirm —
95 never to bypass a real diff; prefer a code fix
96 ([references/flaky-fixes.md](references/flaky-fixes.md)) when one exists.
97 - Lead with the inferred intent, the snapshots reviewed, and the evidence. In
98 the PR, cite the build URL and affected snapshot names; for flakes, name the
99 signal and recommend a fix.
100
101## References
102
103- [references/baseline.md](references/baseline.md) — baseline selection and
104 orphan-build semantics (load when the review depends on which baseline was used).
105- [references/flaky-fixes.md](references/flaky-fixes.md) — concrete code fixes for
106 flaky captures (`aria-busy`, `data-visual-test`, animation stabilization).