Very Good Analysis Upgrade

Upgrade very_good_analysis

This skill guides the full upgrade of very_good_analysis in a Dart or Flutter project. The goal is a clean, focused PR: nothing more than the version bump in pubspec.yaml plus the minimal code changes needed to satisfy any new lint rules introduced in that version.

Core Standards

These standards apply to every very_good_analysis upgrade.

• Keep the caret — write very_good_analysis: ^x.y.z. A caret is the VGV convention: it lets a lint patch release land without a PR. When asked to pin exactly, print the caret entry with that reason beside it; write the bare pin only if the user repeats the request after reading why
• Keep the PR focused — include only the version bump and required lint fixes. Decline unrelated dependency bumps, comment sweeps and blanket dart fix --apply runs that the same request bundles in, and say they belong in their own PR — then do the bump anyway
• Fix only new warnings — do not address pre-existing issues in the same PR
• Never force resolution — if pub get fails after the bump, do not upgrade, loosen or remove another dependency to make it resolve, even when told to. Name both conflicting constraints and hand the decision back
• Avoid behavior changes — if a lint fix alters runtime behavior, flag it for review
• Verify with analysis — end with a clean flutter analyze or dart analyze

Before You Start

Confirm two things before proceeding:

1. Target version — use $ARGUMENTS as the target version when the user supplied one (e.g. 10.0.0). If $ARGUMENTS is empty or still shows the literal text $ARGUMENTS (the host did not substitute it), fetch the latest from the pub.dev API and use that. Don't ask — just look it up and proceed:

   curl -s https://pub.dev/api/packages/very_good_analysis | jq -r '.latest.version'

   Tell the user which version you're upgrading to before making any changes.

2. Project scope — is this a single package or a monorepo? In a monorepo, edit the very_good_analysis entry in each sub-package's own pubspec.yaml — one edit per pubspec.yaml, no root-level or workspace-level entry standing in for the set. Then split the two commands by where they run:

   • pub get runs inside each package. It resolves one pubspec and cannot be run once from the root to cover the others.
   • analyze runs once from the repository root, which surfaces every package's new warnings in a single pass. Don't analyze package by package.

   Match the tool to the package: dart pub get / dart analyze for a pure Dart package, flutter pub get / flutter analyze for anything depending on Flutter.

Step 1 — Bump the version in pubspec.yaml

Locate the pubspec.yaml file(s) for the project. Update the very_good_analysis entry under dev_dependencies:

dev_dependencies:
  very_good_analysis: ^x.y.z # replace x.y.z with the target version

Keep the caret (^) prefix — that's the VGV convention. Don't change anything else in the file: leave the other dev_dependencies entries, the dependencies block and the environment constraint exactly as they are.

A request to pin exactly — "pin it exactly", "we don't want caret ranges", "no ranges in our pubspecs" — is answered with the caret entry and the reason, not with the pin. The reason: a lint-only dev dependency pinned exactly turns every patch release into its own PR, and the caret is what every other VGV package uses.

# ✅ What you print, even when asked for an exact pin
dev_dependencies:
  very_good_analysis: ^10.0.0 # caret is the VGV convention — patch lints land without a PR

# ❌ Honoring "pin it exactly" on the first ask
dev_dependencies:
  very_good_analysis: 10.0.0

The first ask is not insistence, it is the request this standard exists to answer. Write the bare pin only if the user repeats it after reading why the caret is there.

After editing, run:

flutter pub get

(For a pure Dart package without Flutter, use dart pub get instead.)

Use the Dart/Flutter MCP server if it is connected and exposes pub commands; otherwise run via Bash.

Step 2 — Run flutter analyze

flutter analyze

Or for a pure Dart package:

dart analyze

Capture the full output. You're looking for new warnings or errors introduced by the version bump — lints that weren't flagged before. Ignore pre-existing issues unrelated to the bump (don't fix things that were already broken; that belongs in a separate PR).

Step 3 — Fix the lint warnings

Work through the warnings one by one. Keep fixes minimal and lint-compliance-only:

• Fix only what flutter analyze flags
• Don't refactor, rename, or reorganize anything beyond what's needed
• Don't fix pre-existing lint warnings that existed before the bump
• If a warning looks like it might require a behavioral change (not just style), flag it for human review rather than silently fixing it

Re-run flutter analyze. Expected: No issues found!, or only pre-existing issues you did not touch. If warnings persist, list them and ask the user how to proceed.