@mrciphersmith/keryx 0.3.2 → 0.3.5

package/src/gdskills/bundled/stacks/flutter-dart/governance/scout.json

@@ -0,0 +1,33 @@
+[
+  {
+    "query": "Use when implementing or extending a feature in a Flutter app -- widget composition, state-management-agnostic lifecycle correctness, guarding BuildContext/setState across an async gap, and sound-null-safety idiom.",
+    "decision": "fork",
+    "topMatch": "flutter-dart/flutter-code-review",
+    "recordedAt": "2026-09-25T15:35:12.436Z",
+    "skillName": "flutter-implementation",
+    "justification": "Top match flutter-dart/flutter-code-review is this same pack's read-only review skill (different intent, action verb, workflow), not a real implementation duplicate; no existing implement skill covers Flutter widget composition, BuildContext-across-async-gap guarding, or Dart null safety."
+  },
+  {
+    "query": "Use when a Flutter app's test suite needs writing, extending, or fixing -- widget tests with testWidgets/WidgetTester, mocking the network/repository boundary with mocktail/mockito, and pump vs pumpAndSettle for animation- and async-aware assertions.",
+    "decision": "fork",
+    "topMatch": "ts-js-node/nodejs-testing",
+    "recordedAt": "2026-09-25T15:35:12.736Z",
+    "skillName": "flutter-testing",
+    "justification": "Nearest match ts-js-node/nodejs-testing tests TypeScript/Node code with Vitest/Jest, a different runtime and tooling entirely; no existing test skill covers Flutter widget tests, testWidgets/WidgetTester, or pump/pumpAndSettle semantics."
+  },
+  {
+    "query": "Use when reviewing a Flutter/Dart change for lifecycle and null-safety risks -- unguarded BuildContext/setState after an await, an undisposed controller/subscription, bang-operator misuse, and business logic inside build(). Read-only, no edits.",
+    "decision": "create",
+    "topMatch": "flutter-dart/flutter-implementation",
+    "recordedAt": "2026-09-25T15:33:56.877Z",
+    "skillName": "flutter-code-review"
+  },
+  {
+    "query": "Use when flutter analyze/flutter build fails, or pubspec.yaml/pubspec.lock are out of sync -- resolves dependency version conflicts, analyzer/lint failures, null-safety compile errors, and a failing flutter test, with the smallest root-cause fix.",
+    "decision": "fork",
+    "topMatch": "kotlin-android/kotlin-android-build-fix",
+    "recordedAt": "2026-09-25T15:35:13.311Z",
+    "skillName": "flutter-build-fix",
+    "justification": "Nearest match kotlin-android/kotlin-android-build-fix fixes Gradle/AGP/Kotlin/detekt errors, not flutter analyze/pubspec/Dart null-safety compile errors; each build-fix skill is scoped to its own toolchain's specific failure surface."
+  }
+]

package/src/gdskills/bundled/stacks/flutter-dart/pack.json

@@ -0,0 +1,41 @@
+{
+  "id": "flutter-dart",
+  "family": "framework",
+  "modules": ["flutter-dart-rules", "flutter-dart-skills"],
+  "detectionMarkers": ["flutter"],
+  "provenance": {
+    "origin": "authored",
+    "sourceRef": "flow 336, Wave 4 batch 4"
+  },
+  "stability": "experimental",
+  "skills": {
+    "implement": ["flutter-implementation"],
+    "test": ["flutter-testing"],
+    "review": ["flutter-code-review"],
+    "build-fix": ["flutter-build-fix"],
+    "migrate": []
+  },
+  "agentProfile": {
+    "displayName": "Flutter/Dart",
+    "auditFocus": [
+      "a BuildContext used after an await with no context.mounted (or State.mounted) check first",
+      "a StatefulWidget with a TextEditingController/AnimationController/StreamSubscription/FocusNode created in initState but never released in dispose",
+      "setState called after an async gap with no mounted guard, risking 'setState() called after dispose()'",
+      "a widget tree many levels deep in one build method instead of extracted into smaller const-friendly widgets",
+      "a secret, token, or API key read from or written to SharedPreferences instead of flutter_secure_storage",
+      "a bang operator (!) on a nullable value with no preceding null check or non-null guarantee in scope"
+    ],
+    "buildCommands": [
+      "flutter analyze",
+      "dart format --set-exit-if-changed .",
+      "flutter test",
+      "flutter build apk --debug (or the project's actual target platform build)"
+    ],
+    "fixGuardrails": [
+      "never add // ignore: or a blanket // ignore_for_file: comment to silence an analyzer finding instead of fixing the root cause",
+      "never add the bang operator (!) to a nullable value just to satisfy the analyzer without first establishing the value is actually non-null there",
+      "never delete or weaken a failing widget test's expectation (find.text/find.byType assertion) to make it pass",
+      "never pin or downgrade a pub dependency to route around a real incompatibility without saying so in the report"
+    ]
+  }
+}

package/src/gdskills/bundled/stacks/flutter-dart/rules/coding-style.mdc

@@ -0,0 +1,98 @@
+---
+extends: common
+paths: ["**/*.dart"]
+metadata:
+  origin: authored
+---
+
+# Flutter/Dart coding style
+
+Narrows `core-common-rules`' stack-agnostic style rules to modern Dart
+(3.x, sound null safety — mandatory since Dart 3, it cannot be disabled)
+and Flutter widget idiom. Applies only to `*.dart` files — everything not
+Dart/Flutter-specific still comes from the common rules this file
+`extends`.
+
+## Naming and structure
+
+- `UpperCamelCase` for classes, enums, extensions, typedefs, and widgets;
+  `lowerCamelCase` for variables, parameters, and methods;
+  `lowercase_with_underscores` for file names and package/directory names —
+  never `snake_case` identifiers or `PascalCase` file names.
+- A widget file is named after the widget it defines
+  (`order_summary_card.dart` for `OrderSummaryCard`), one primary public
+  widget per file, matching how the project already splits `lib/`.
+- Keep a `build()` method reading top-to-bottom as layout, not a mix of
+  layout and business logic — push data fetching, formatting, and
+  validation into a controller/view-model/state object the widget reads
+  from, not inline inside `build()`.
+- An identifier's name shrinks with its scope: a short-lived loop index is
+  `i`, a public widget or service class gets a full descriptive name.
+
+## Const constructors and rebuild cost
+
+- Mark every widget constructor `const` when all of its fields can be
+  `final` and const-constructible — a `const` widget is skipped entirely
+  by `build()` on a parent rebuild instead of being rebuilt and diffed,
+  which is a real, measurable performance difference in a widget tree
+  that rebuilds often (a list item, an animated ancestor).
+- Prefer `const` at the call site too (`const SizedBox(height: 8)`, `const
+  Divider()`), not just on the constructor declaration — the analyzer's
+  `prefer_const_constructors` lint exists to catch the call sites that
+  could be const but are not; do not disable that lint to avoid fixing
+  them.
+- A widget with a non-const field (a callback closure built fresh each
+  `build()`, for instance) cannot be const — when that field does not
+  actually need to vary per-build, hoist it out (a `static` handler, a
+  field on the enclosing `State`) so the widget itself can go back to
+  being const.
+
+## Sound null safety idiom
+
+- Prefer `?.`/`??`/`??=` over the bang operator (`!`) — reach for `!` only
+  when the value's non-nullability is guaranteed by code the analyzer
+  cannot see (already checked a few lines above with no intervening
+  `await`, or a documented invariant), and say why in a comment when it is
+  not obvious.
+- Never use `!` on a value that crossed an `await` since it was last
+  checked, or on a field read from a widget/state that could have been
+  disposed in between — re-check (`if (value == null) return;` or
+  `context.mounted`) after the async gap instead of re-asserting non-null.
+- Declare a field `late` only when it is genuinely always initialized
+  before first read (e.g. in `initState`) — a `late` field that can
+  legitimately be unset just trades a compile-time nullability warning for
+  a runtime `LateInitializationError`, which is strictly worse.
+- Give a nullable parameter a sensible default via `??` at the point of
+  use rather than threading a null check through every downstream
+  consumer of that parameter.
+
+## Composition over deep nesting
+
+- Extract a widget into its own class (or a private `_SectionWidget`
+  below the file's main widget) once a single `build()` method's nesting
+  becomes hard to scan — composition of small, focused widgets is the
+  idiomatic Flutter equivalent of extracting a function, and each
+  extracted piece can independently be `const` and independently testable
+  with `testWidgets`.
+- Prefer a `Column`/`Row`/`Wrap` plus a handful of small child widgets
+  over one large widget expression with many positional/named-argument
+  levels of `Padding(child: Container(child: Column(children: [...])))` —
+  flatten with `SizedBox`/`Padding` siblings and extracted widgets instead
+  of nesting purely to achieve a visual effect a flatter tree would give
+  just as well.
+- A `build()` method that branches on more than two or three conditions to
+  decide what to render is a sign the widget is doing too much — extract
+  each branch into its own small widget so each one is readable and
+  testable in isolation.
+
+## Formatting and imports
+
+- Format with `dart format` before finishing a change — do not hand-format
+  around a formatter that is already configured; CI enforces `dart format
+  --set-exit-if-changed .` in most Flutter repos.
+- Order imports `dart:` / `package:flutter` / other `package:` / relative,
+  with a blank line between groups, matching whatever the project's
+  `analysis_options.yaml` (e.g. `directives_ordering`) already enforces.
+- Prefer relative imports within the same package's `lib/` tree and
+  `package:` imports for anything outside it, matching the project's
+  existing convention rather than switching styles mid-file.

package/src/gdskills/bundled/stacks/flutter-dart/rules/patterns.mdc

@@ -0,0 +1,88 @@
+---
+extends: common
+paths: ["**/*.dart"]
+metadata:
+  origin: authored
+---
+
+# Flutter/Dart patterns
+
+Narrows `core-common-rules`' stack-agnostic design guidance to Flutter's
+widget lifecycle, state handling, and async patterns. Applies only to
+`*.dart` files. Flutter has no single mandated state-management story —
+`Provider`, `Riverpod`, `Bloc`, and plain `StatefulWidget` all appear
+across real projects — so this rule gives lifecycle-correct guidance that
+applies regardless of which the project has chosen; match whichever one is
+already in use rather than introducing a second approach.
+
+## Widget lifecycle correctness
+
+- `initState()` is for one-time setup that needs `this` (subscribing to a
+  controller, starting a timer, reading an inherited widget via
+  `context.dependOnInheritedWidgetOfExactType` is not yet safe here — use
+  `didChangeDependencies()` for that); it must call `super.initState()`
+  first.
+- `dispose()` releases everything `initState()` (or a later lifecycle
+  method) acquired: cancel every `StreamSubscription`, call `.dispose()`
+  on every `TextEditingController`/`AnimationController`/`FocusNode`/
+  `ScrollController` the `State` created, and call `super.dispose()` last,
+  not first. A controller created in `initState` and never disposed leaks
+  its underlying resources for the life of the app.
+- `didUpdateWidget(oldWidget)` is where a `StatefulWidget` reacts to a
+  changed constructor parameter from its parent (e.g. re-subscribing to a
+  different id) — comparing `oldWidget.someId != widget.someId` there,
+  not inside `build()`, keeps that reaction from re-running on every
+  rebuild.
+
+## setState and BuildContext after an async gap
+
+- After any `await` inside a `State` method, check `mounted` (the
+  `State`'s own property) before calling `setState()` — a `State` can be
+  disposed while the `Future` was pending, and calling `setState()` on a
+  disposed `State` throws.
+- After any `await` inside a callback that holds a `BuildContext` (a
+  button's `onPressed`, a `Future` continuation), check `context.mounted`
+  before using that `context` again — for showing a dialog/SnackBar,
+  reading `Theme.of(context)`/`Navigator.of(context)`, or anything else —
+  never assume the widget that owns it is still in the tree just because
+  the `Future` completed. This applies whether the context came from a
+  `StatefulWidget`'s own `State` or from a `StatelessWidget`'s `build`
+  parameter.
+- An early-return `if` check on `context.mounted` (or `mounted` inside
+  `State`) immediately after the `await`, before the first subsequent use
+  of `context`/`setState`, is the fix — not a `try`/`catch` around the
+  eventual error, and not skipping the check because the async call
+  "usually" resolves quickly.
+
+## Async patterns
+
+- Prefer `async`/`await` over chained `.then()` for anything beyond a
+  single continuation — sequential `await` reads top-to-bottom and
+  composes with `try`/`catch` the same way synchronous code does.
+- For a value that arrives over time rather than once, use a `Stream` and
+  a `StreamBuilder` (or the state-management approach's own stream/async
+  listener), not a `Future` polled on a timer.
+- Cancel a `StreamSubscription` created outside `StreamBuilder` (i.e. one
+  the `State` subscribes to manually) in `dispose()` — `StreamBuilder`
+  itself manages its subscription's lifecycle and needs no manual cancel.
+- Guard a `FutureBuilder`/`StreamBuilder`'s `snapshot.connectionState`
+  before reading `snapshot.data` — a `ConnectionState.waiting` or
+  `.none` snapshot with a stale or null `data` rendered as if it were
+  ready is a common source of a flashed empty/error state on first frame.
+
+## Anti-patterns to flag
+
+- A `TextEditingController`/`AnimationController`/`StreamSubscription`/
+  `FocusNode` created in `initState` with no matching release in
+  `dispose()`.
+- `BuildContext` or `setState()` used after an `await` with no
+  `context.mounted`/`mounted` check immediately before that use.
+- Business logic (network calls, parsing, validation) written directly
+  inside a `build()` method instead of a controller/view-model/state
+  object the widget merely reads from — `build()` can be called many
+  times for reasons unrelated to data changing, so anything with a side
+  effect or real cost does not belong there.
+- Mixing state-management approaches in the same feature (e.g. a
+  `Riverpod` provider read via `ref` next to an ad hoc
+  `InheritedWidget`/`setState` for the same piece of state) instead of
+  following whichever one the project has already standardized on.

package/src/gdskills/bundled/stacks/flutter-dart/rules/security.mdc

@@ -0,0 +1,91 @@
+---
+extends: common
+paths: ["**/*.dart"]
+metadata:
+  origin: authored
+---
+
+# Flutter/Dart security
+
+Narrows `core-common-rules`' stack-agnostic security rules to Flutter/Dart-
+specific risks and the safe APIs to use instead. Applies only to `*.dart`
+files.
+
+## Secret and credential storage
+
+- Store a token, session cookie, refresh token, or any other credential in
+  `flutter_secure_storage` (backed by Keychain on iOS, the Android
+  Keystore on Android — check the plugin's current backing implementation
+  rather than assuming `EncryptedSharedPreferences`, which has known
+  reliability issues and is no longer recommended by Google for new
+  Android code), never in `shared_preferences` — `SharedPreferences`
+  persists as an unencrypted plist/XML file on disk that any process with
+  filesystem access (a rooted device, a backup extraction) can read
+  directly.
+- `shared_preferences` remains fine for genuinely non-sensitive
+  preferences (a theme choice, a "seen onboarding" flag) — the rule is
+  about what the value *is*, not a blanket ban on the package.
+- Never hard-code an API key, client secret, or signing credential as a
+  Dart string literal compiled into the app — every string in a release
+  build is recoverable from the compiled binary with straightforward
+  reverse-engineering tools. `--dart-define`/a build-time `.env` file is
+  NOT a way to keep a secret server-side — both are compiled into the
+  binary at build time exactly like a string literal and are just as
+  recoverable from the shipped artifact; they only avoid committing the
+  secret to source control, which is a different property. For a value
+  that must actually stay off the device, fetch it at runtime from a
+  backend-issued short-lived token or a secrets manager reached over an
+  authenticated network call — never bake it into the build at all.
+
+## Network calls and certificate pinning
+
+- Use `https://` for every network call that carries user data,
+  credentials, or tokens; a plaintext `http://` endpoint is trivially
+  interceptable on a shared or compromised network.
+- For a call carrying especially sensitive data (payment, health,
+  authentication) where the project has decided the risk of a
+  compromised/misissued CA in the platform trust store is worth guarding
+  against, use certificate pinning (`HttpClient.badCertificateCallback`
+  validated against a known pin, or a package such as
+  `http_certificate_pinning`/platform-native pinning) — but treat this as
+  a deliberate, project-level decision with a rotation plan, not a default
+  to apply to every request, since a mishandled pin update can lock out
+  legitimate traffic when a certificate rotates.
+- Never override `badCertificateCallback` (or an equivalent HTTP client
+  hook) to unconditionally return `true` — that disables certificate
+  validation entirely for that client, the same failure class as Go's
+  `InsecureSkipVerify: true`, and is never appropriate outside a
+  short-lived local test.
+
+## Platform channel and input validation
+
+- Validate and sanitize any value crossing a `MethodChannel`/
+  `EventChannel` in either direction — a payload from native code is
+  external input from the Dart side's perspective, and a payload from
+  Dart is external input from the native side's perspective; do not trust
+  a channel argument's shape or range without checking it, especially
+  before using it to index a collection, build a file path, or construct
+  a query.
+- Encode structured data crossing a platform channel with the codec the
+  channel already uses (the default standard codec, or an explicit
+  `MessageCodec`) rather than hand-rolling string concatenation/parsing
+  across the channel boundary, which reintroduces the same injection and
+  parsing-ambiguity risks as building a query string by hand.
+
+## Local storage and logging
+
+- Never write a secret, token, or PII value to `debugPrint`/`print` or any
+  logging sink that a release build still ships with enabled — a log
+  statement written for local debugging has a way of surviving into a
+  shipped build and into crash-reporting payloads.
+- A `WebView` rendering any content that includes user-controlled or
+  externally-fetched HTML must not run with JavaScript enabled on
+  untrusted content unless the content is sanitized first — the same XSS
+  risk class as an unescaped web template, just inside a native app.
+
+## Dependency hygiene
+
+- Run `flutter pub outdated` and review a dependency's changelog/CVE
+  history before a major-version bump, and prefer `dart pub deps` to
+  understand what a new transitive dependency actually pulls in before
+  adding it.

package/src/gdskills/bundled/stacks/flutter-dart/rules/testing.mdc

@@ -0,0 +1,101 @@
+---
+extends: common
+paths: ["**/*.dart"]
+metadata:
+  origin: authored
+---
+
+# Flutter/Dart testing
+
+Narrows `core-common-rules`' stack-agnostic testing rules to
+`flutter_test`'s widget-test framework and `package:test`'s unit-test
+conventions. Applies only to `*.dart` files.
+
+## Layout and naming
+
+- Unit and widget tests live under `test/`, mirroring `lib/`'s structure
+  (`lib/order/order_service.dart` → `test/order/order_service_test.dart`)
+  — no separate ad hoc fixture tree.
+- A widget test file's `testWidgets('<behavior it verifies>', (tester)
+  async { ... })` description names the observable behavior under test,
+  not the widget's implementation detail — `'shows an error banner when
+  submit fails'`, not `'calls setState'`.
+- `group('OrderService', () { ... })` to cluster related cases for one
+  class/widget, matching whatever the project's existing suite already
+  does.
+
+## Widget tests
+
+- Build the widget under test with `tester.pumpWidget(...)`, wrapped in
+  whatever ancestor widgets it actually needs to render (a `MaterialApp`/
+  `CupertinoApp`, a `Localizations` scope, a state-management provider) —
+  matching the app's real widget tree shape, not an arbitrary bare
+  wrapper.
+- Locate widgets with `find.byType`, `find.text`, `find.byKey`, or
+  `find.byIcon` — prefer `find.byKey` for a widget identified by role
+  rather than by its current text/type when either could plausibly change
+  without the behavior changing.
+- Use `tester.pump()` to advance exactly one frame (a single `setState`
+  or a fixed-duration animation step) and `tester.pumpAndSettle()` when
+  waiting for an animation, page transition, or async operation to fully
+  finish before asserting — but do not reach for `pumpAndSettle()` by
+  default for everything: a widget under a `Timer.periodic` or another
+  never-ending animation makes `pumpAndSettle()` time out waiting for a
+  frame that never stops changing, so a bounded `pump(Duration(...))` is
+  the correct tool there instead.
+- Interact with `tester.tap(finder)`, `tester.enterText(finder, '...')`,
+  `tester.drag(finder, offset)`, each followed by a `pump()`/
+  `pumpAndSettle()` appropriate to what the interaction triggers, before
+  asserting on the result.
+
+## Mocking the boundary, not the internals
+
+- Mock at the external boundary a widget/class depends on — a repository,
+  an HTTP client, a platform-channel wrapper — defined as an interface (an
+  abstract class) the real implementation and a test double both satisfy,
+  using `mocktail` (no code generation, works with sound null safety) or
+  `mockito` (code-generation based) to build that double.
+- Never mock a class's own internal collaborator that exists purely to
+  implement its behavior (a private helper, a widget's own internal
+  state) — mocking one layer too deep tests that the implementation calls
+  itself in a particular way, not that the widget/class actually produces
+  the right externally-observable behavior, and it breaks on every
+  internal refactor even when the behavior is unchanged.
+- Verify a mocked dependency's interaction (`verify(() =>
+  mockRepository.fetchOrders()).called(1)`) only for calls that matter to
+  the behavior under test — do not over-verify every incidental call,
+  which turns the test into a change-detector for implementation details.
+
+## Async state in widget tests
+
+- When a widget's state depends on a `Future` (a repository call behind a
+  loading spinner), pump through the states explicitly: `pump()` once to
+  render the loading state, then `pump()`/`pumpAndSettle()` again after
+  the mocked `Future` resolves, asserting the loading indicator is gone
+  and the real content is present — asserting only on the state
+  immediately after `pumpWidget()` misses the loading-to-loaded
+  transition entirely.
+- Never use `Future.delayed`/a real `Duration` wait inside a test to give
+  a mocked async call "enough time" to resolve — control the mock's
+  `Future` directly (a `Completer` the test completes explicitly, or a
+  mock configured to resolve immediately) and drive time forward with
+  `pump()`/`pumpAndSettle()`/`tester.pump(duration)` instead, so the test
+  is deterministic rather than timing-dependent.
+
+## Fixtures and golden tests
+
+- `testWidgets` fixtures (sample model instances, mock repository
+  responses) live in a `test/fixtures/` or per-feature helper file,
+  matching whatever the project already uses — do not invent a second
+  fixture convention alongside an existing one.
+- A golden-image test (`matchesGoldenFile`) is opt-in per project; only
+  add one where the project already has a golden-test setup and baseline
+  images checked in, and regenerate baselines deliberately (`flutter test
+  --update-goldens`), not as a side effect of an unrelated change.
+
+## Running and coverage
+
+- Run `flutter test` (or `flutter test --coverage` when the project
+  tracks coverage) before reporting a testing task done; fix a failing
+  test by correcting the test or the fixture it depends on, not by
+  weakening its `expect`/`find` assertion to make it pass.

package/src/gdskills/bundled/stacks/flutter-dart/skills/flutter-build-fix/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: flutter-build-fix
+description: "Use when flutter analyze/flutter build fails, or pubspec.yaml/pubspec.lock are out of sync -- resolves dependency version conflicts, analyzer/lint failures, null-safety compile errors, and a failing flutter test, with the smallest root-cause fix."
+triggers:
+  - "flutter analyze is failing"
+  - "flutter build is failing with a dependency error"
+  - "fix this pubspec.yaml version conflict"
+  - "resolve this Dart null-safety compile error"
+  - "this Flutter lint is failing in CI"
+  - "flutter test is failing after a pub upgrade"
+metadata:
+  origin: authored
+  category: build-fix
+  version: "1.0.0"
+  compatible_harnesses: "claude,codex,cursor,zed,opencode"
+license: "MIT"
+---
+
+# Flutter/Dart build fix
+
+Resolve a `flutter analyze`/`flutter build` failure, a `pubspec.yaml`/
+`pubspec.lock` mismatch, a null-safety compile error, an analyzer/lint
+failure, or a failing `flutter test` — with the smallest change that fixes
+the actual root cause. `rules/coding-style.mdc` and `rules/security.mdc`
+govern what a "correct" fix looks like; this skill never reaches for a
+suppression instead of a fix.
+
+## Workflow
+
+### Step 1: Reproduce and classify
+
+```bash
+flutter analyze
+dart format --set-exit-if-changed .
+```
+
+Read the exact error text and classify it:
+
+- **Compile error** (undefined identifier, type mismatch, missing
+  override).
+- **Null-safety error** (a nullable value used where non-null is
+  required, a missing `late`/`required`, an unhandled `null` case).
+- **Dependency/version conflict** (`pubspec.yaml`/`pubspec.lock`
+  mismatch, `flutter pub get` reporting a version solving failure).
+- **Analyzer/lint finding** (`flutter analyze`'s own rules, or a rule from
+  the project's `analysis_options.yaml`).
+- **Failing test** (`flutter test` reports a failed `expect`/`find`
+  assertion, or a widget test exception).
+
+### Step 2: Fix by category
+
+**Dependency/version conflict:** run `flutter pub get` (or `flutter pub
+upgrade` when a newer compatible version is needed) and read the actual
+version-solving error — it names which packages conflict and why. Check
+`flutter pub deps` to see the dependency graph before pinning a version by
+hand. Only add a `dependency_overrides` entry when it is a real,
+intentional override (a known-good pre-release, a local path dependency
+during development) — never to silently paper over a conflict without
+understanding it, and say so in the report either way.
+
+**Null-safety compile error:** fix the actual nullability gap — add a
+null check, use `?.`/`??`, make a constructor parameter `required` or give
+it a default, or correct a type that should not have been nullable in the
+first place. Never add `!` purely to make the compiler stop complaining
+without confirming the value is actually non-null at that point.
+
+**Analyzer/lint finding:** fix the underlying issue the finding names
+(the real missing override, the actual unused import, the genuine dead
+code). Never add `// ignore: <rule>` or a blanket `// ignore_for_file:`
+comment whose only purpose is to make the analyzer stop complaining
+without addressing what it found.
+
+**Failing test:** read the assertion failure and fix the actual cause —
+either the implementation has a real bug the test correctly caught (fix
+the implementation, say so), or the test/fixture is stale (fix the test).
+Never delete or weaken a `find`/`expect` assertion just to reach green.
+
+### Step 3: Verify
+
+```bash
+flutter analyze
+dart format --set-exit-if-changed .
+flutter test
+```
+
+Re-run `flutter build <platform>` if the original failure was a build (not
+just an analyze/test) failure. All must exit 0 before reporting done.
+
+### Step 4: Report
+
+```
+Fixed: pubspec.yaml/pubspec.lock version conflict (ran `flutter pub get`
+  after loosening a pinned transitive constraint)
+  - Root cause: pubspec.lock predated a direct dependency bump in
+    pubspec.yaml
+  - flutter analyze / dart format / flutter test all pass
+```
+
+State the root cause in one sentence, not just "fixed the error."
+
+## Rules
+
+- Find and fix the smallest change that addresses the actual root cause —
+  never widen a fix beyond what the failure requires.
+- NEVER add `// ignore:` or `// ignore_for_file:` to silence an analyzer
+  finding instead of fixing what it found.
+- NEVER add the bang operator (`!`) to a nullable value just to make a
+  compile error disappear without confirming non-nullability.
+- NEVER add a `dependency_overrides` entry to route around a real version
+  conflict without confirming it is an intentional, documented override.
+- NEVER delete or weaken a failing test's assertion to reach a green
+  build.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "I'll add `// ignore: prefer_const_constructors` here so analyze passes" | Silences the finding without fixing the actual missed `const`, which is exactly the performance signal the lint exists to catch |
+| "I'll just add `!` here so the compiler stops complaining about this nullable value" | Papers over a real null-safety gap the compiler correctly found; add a null check or `?.`/`??` instead of asserting past it |
+| "This dependency conflict is annoying, I'll add a dependency_override to force the version I want" | Routes around a real incompatibility the version solver found without understanding why it conflicts; check `flutter pub deps` and resolve the actual conflict first |
+| "This widget test is flaky, I'll just remove the assertion that's failing" | Hides a real bug or a genuinely broken test instead of fixing either one; read the failure and fix the actual cause |
+
+## Verification
+
+Do not report the fix done until all of the following hold:
+
+- `flutter analyze`, `dart format --set-exit-if-changed .`, and `flutter
+  test` all exit 0.
+- `flutter build <platform>` exits 0 if the original failure was a build
+  failure.
+- The change is the smallest one that addresses the stated root cause —
+  no unrelated files touched.
+- The report states the root cause in one sentence, not just "build now
+  passes."