update-snapshots

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, generated by the help_all_golden test in 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:

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

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:

cargo insta test --test integration_test --no-quiet

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

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:

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:

  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

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/. 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 §STYLE-0010 (testing tag).