---
name: update-snapshots
description: Reviews and updates `insta` golden snapshots after changes to user-visible CLI surface (subcommands, flags, help text, error messages). Invoke whenever a change touches `src/cli/**`, `src/main.rs`, `#[derive(Parser)]`, or `#[arg(...)]` sites — *before* declaring the work done. Triggers on terms like "snapshot", "insta", "golden", "help_all", and "snap".
allowed-tools: Bash, Read
---

# Update Snapshots

Review and accept (or reject) `insta` snapshot drift after changes that affect the
CLI surface. The most frequently affected golden file is
[tests/snapshots/integration_test__help_all_output.snap](tests/snapshots/integration_test__help_all_output.snap),
generated by the `help_all_golden` test in
[tests/integration_test.rs](tests/integration_test.rs).

`./scripts/build.sh` runs `cargo build`, `cargo fmt --check`, `cargo clippy`, and
`cargo test`, so plain build-script success is *not* enough — snapshot drift will
surface in `cargo test` and CI will fail until the `.snap` file is updated to match
the new output.

## When to invoke

Invoke this skill whenever the change touches any of:

- `src/cli/**` — clap command/subcommand definitions, help text
- `src/main.rs` — top-level CLI wiring
- Any `#[derive(Parser)]`, `#[derive(Subcommand)]`, `#[command(...)]`, or `#[arg(...)]` site
- Error messages or other output covered by an `insta::assert_snapshot!` call

A quick way to detect this against the working tree:

```bash
git diff --name-only HEAD -- src/cli src/main.rs
git diff HEAD -- src | grep -E '#\[(derive\(Parser|derive\(Subcommand|command|arg)'
```

If either produces output, run the steps below before declaring the work done.

## Step 1 — Run the snapshot tests

```bash
cargo insta test --test integration_test --review
```

`--review` runs the tests and, if any snapshot has drifted, drops you into an
interactive review. From a non-interactive context, use:

```bash
cargo insta test --test integration_test --no-quiet
```

…and then inspect the produced `.snap.new` files manually:

```bash
git status --porcelain tests/snapshots/
ls tests/snapshots/*.snap.new 2>/dev/null
```

## Step 2 — Decide: accept or investigate

For each pending snapshot, diff it against the committed file:

```bash
diff -u tests/snapshots/<name>.snap tests/snapshots/<name>.snap.new
```

Then choose:

- **Accept** the new snapshot when the diff reflects an *intended* change — every
  added / removed / modified line corresponds to a CLI change you just made (new
  subcommand, renamed flag, edited help text, etc.). The fix is:

  ```bash
  cargo insta accept --test integration_test
  ```

  …or equivalently `cargo insta test --test integration_test --accept`. Stage the
  updated `.snap` file alongside the source change in the same commit so the diff
  is reviewable end-to-end.

- **Investigate** when the diff contains anything you did *not* intend — for
  example:
  - Lines disappear that you did not remove (a subcommand silently dropped from
    the help tree)
  - Flag default values change unexpectedly
  - Help text for an unrelated command shifts
  - Ordering changes that suggest a regression in the help generator

  Do not run `--accept`. Read the diff, identify the regression, fix the source,
  and re-run Step 1.

## Step 3 — Re-run the full test suite

```bash
cargo test
```

A clean `cargo test` after acceptance confirms the snapshot is committed and the
broader suite is unaffected.

## Notes

- Never run `cargo insta accept` blindly. Accepting drift you did not cause is how
  silent regressions ship.
- Snapshots live next to the test that produced them under
  [tests/snapshots/](tests/snapshots/). The naming convention is
  `<test_module>__<snapshot_name>.snap`.
- If a `.snap.new` file is present in `git status` but not produced by your
  changes, re-run `cargo test` to regenerate, then investigate — it is likely a
  stale artefact from a previous failed run.
- For background and motivation, see
  [docs/STYLE_GUIDE.md](docs/STYLE_GUIDE.md) §STYLE-0010 (`testing` tag).