opencode-agent-kit 1.0.0

package/template/.opencode/skills/continuous-learning-v2/scripts/test_parse_instinct.py

@@ -0,0 +1,82 @@
+"""Tests for parse_instinct_file() — verifies content after frontmatter is preserved."""
+
+import importlib.util
+import os
+
+# Load instinct-cli.py (hyphenated filename requires importlib)
+_spec = importlib.util.spec_from_file_location(
+    "instinct_cli",
+    os.path.join(os.path.dirname(__file__), "instinct-cli.py"),
+)
+_mod = importlib.util.module_from_spec(_spec)
+_spec.loader.exec_module(_mod)
+parse_instinct_file = _mod.parse_instinct_file
+
+
+MULTI_SECTION = """\
+---
+id: instinct-a
+trigger: "when coding"
+confidence: 0.9
+domain: general
+---
+
+## Action
+Do thing A.
+
+## Examples
+- Example A1
+
+---
+id: instinct-b
+trigger: "when testing"
+confidence: 0.7
+domain: testing
+---
+
+## Action
+Do thing B.
+"""
+
+
+def test_multiple_instincts_preserve_content():
+    result = parse_instinct_file(MULTI_SECTION)
+    assert len(result) == 2
+    assert "Do thing A." in result[0]["content"]
+    assert "Example A1" in result[0]["content"]
+    assert "Do thing B." in result[1]["content"]
+
+
+def test_single_instinct_preserves_content():
+    content = """\
+---
+id: solo
+trigger: "when reviewing"
+confidence: 0.8
+domain: review
+---
+
+## Action
+Check for security issues.
+
+## Evidence
+Prevents vulnerabilities.
+"""
+    result = parse_instinct_file(content)
+    assert len(result) == 1
+    assert "Check for security issues." in result[0]["content"]
+    assert "Prevents vulnerabilities." in result[0]["content"]
+
+
+def test_empty_content_no_error():
+    content = """\
+---
+id: empty
+trigger: "placeholder"
+confidence: 0.5
+domain: general
+---
+"""
+    result = parse_instinct_file(content)
+    assert len(result) == 1
+    assert result[0]["content"] == ""

package/template/.opencode/skills/dart-add-unit-test/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: dart-add-unit-test
+description: Write and organize unit tests for functions, methods, and classes using `package:test`. Use when creating new logic or fixing bugs to ensure code remains correct and regression-free.
+metadata:
+  model: models/gemini-3.1-pro-preview
+  last_modified: Fri, 24 Apr 2026 15:07:58 GMT
+---
+# Testing Dart and Flutter Applications
+
+## Contents
+- [Structuring Test Files](#structuring-test-files)
+- [Writing Tests](#writing-tests)
+- [Executing Tests](#executing-tests)
+- [Test Implementation Workflow](#test-implementation-workflow)
+- [Examples](#examples)
+
+## Structuring Test Files
+Organize test files to mirror the `lib` directory structure to maintain predictability.
+
+* Place all test code within the `test` directory at the root of the package.
+* Append `_test.dart` to the end of all test file names (e.g., `lib/src/utils.dart` should be tested in `test/src/utils_test.dart`).
+* If writing integration tests, place them in an `integration_test` directory at the root of the package.
+
+## Writing Tests
+Utilize `package:test` as the standard testing library for Dart applications.
+
+* Import `package:test/test.dart` (or `package:flutter_test/flutter_test.dart` for Flutter).
+* Group related tests using the `group()` function to provide shared context.
+* Define individual test cases using the `test()` function.
+* Validate outcomes using the `expect()` function alongside matchers (e.g., `equals()`, `isTrue`, `throwsA()`).
+* Write asynchronous tests using standard `async`/`await` syntax. The test runner automatically waits for the `Future` to complete.
+* Manage test setup and teardown using `setUp()` and `tearDown()` callbacks.
+* If testing code that relies on dependency injection, use `package:mockito` alongside `package:test` to generate mock objects, configure fixed scenarios, and verify interactions.
+
+## Executing Tests
+Select the appropriate test runner based on the project type and test location.
+
+* If working on a pure Dart project, execute tests using the `dart test` command.
+* If working on a Flutter project, execute tests using the `flutter test` command.
+* If running integration tests, explicitly specify the directory path, as the default runner ignores it: `dart test integration_test` or `flutter test integration_test`.
+
+## Test Implementation Workflow
+
+Follow this sequential workflow when implementing new test suites. Copy the checklist to track your progress.
+
+### Task Progress
+- [ ] 1. Create the test file in the `test/` directory, ensuring the `_test.dart` suffix.
+- [ ] 2. Import `package:test/test.dart` and the target library.
+- [ ] 3. Define a `main()` function.
+- [ ] 4. Initialize shared resources or mocks using `setUp()`.
+- [ ] 5. Write `test()` cases grouped by functionality using `group()`.
+- [ ] 6. Execute the test suite using the appropriate CLI command.
+- [ ] 7. **Feedback Loop**: Run test -> Review stack trace for failures -> Fix implementation or assertions -> Re-run until passing.
+
+## Examples
+
+### Standard Unit Test Suite
+Demonstrates grouping, setup, synchronous, and asynchronous testing.
+
+```dart
+import 'package:test/test.dart';
+import 'package:my_package/calculator.dart';
+
+void main() {
+  group('Calculator', () {
+    late Calculator calc;
+
+    setUp(() {
+      calc = Calculator();
+    });
+
+    test('adds two numbers correctly', () {
+      expect(calc.add(2, 3), equals(5));
+    });
+
+    test('handles asynchronous operations', () async {
+      final result = await calc.fetchRemoteValue();
+      expect(result, isNotNull);
+      expect(result, greaterThan(0));
+    });
+  });
+}
+```
+
+### Mocking with Mockito
+Demonstrates configuring a mock object for dependency injection testing.
+
+```dart
+import 'package:test/test.dart';
+import 'package:mockito/mockito.dart';
+import 'package:mockito/annotations.dart';
+import 'package:my_package/api_client.dart';
+import 'package:my_package/data_service.dart';
+
+// Generate the mock using build_runner: dart run build_runner build
+@GenerateNiceMocks([MockSpec<ApiClient>()])
+import 'data_service_test.mocks.dart';
+
+void main() {
+  group('DataService', () {
+    late MockApiClient mockApiClient;
+    late DataService dataService;
+
+    setUp(() {
+      mockApiClient = MockApiClient();
+      dataService = DataService(apiClient: mockApiClient);
+    });
+
+    test('returns parsed data on successful API call', () async {
+      // Configure the mock
+      when(mockApiClient.get('/data')).thenAnswer((_) async => '{"id": 1}');
+
+      // Execute the system under test
+      final result = await dataService.fetchData();
+
+      // Verify outcomes and interactions
+      expect(result.id, equals(1));
+      verify(mockApiClient.get('/data')).called(1);
+    });
+  });
+}
+```

package/template/.opencode/skills/dart-build-cli-app/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: dart-build-cli-app
+description: Entrypoint structure, exit codes, cross-platform scripts. Use when building command line utilities, scripts, or applications.
+metadata:
+  model: models/gemini-3.1-pro-preview
+  last_modified: Fri, 04 May 2026 17:41:00 GMT
+---
+# Building Dart CLI Applications
+
+## Contents
+- [Project Setup & Architecture](#project-setup--architecture)
+- [Argument Parsing & Command Routing](#argument-parsing--command-routing)
+- [Execution & Error Handling](#execution--error-handling)
+- [Testing CLI Applications](#testing-cli-applications)
+- [Compilation & Distribution](#compilation--distribution)
+- [Workflows](#workflows)
+- [Examples](#examples)
+
+## Project Setup & Architecture
+
+Initialize new CLI projects using the official Dart template to ensure standard directory structures.
+
+*   Run `dart create -t cli <project_name>` to scaffold a console application with basic argument parsing.
+*   Place executable entry points (files containing `main()`) exclusively in the `bin/` directory.
+*   Place internal implementation logic in `lib/src/` and expose public APIs via `lib/<project_name>.dart`.
+*   Enforce formatting in CI environments by running `dart format . --set-exit-if-changed`. This returns exit code 1 if formatting violations exist.
+
+## Argument Parsing & Command Routing
+
+Import the `args` package to manage command-line arguments, flags, and subcommands.
+
+*   If building a simple script: Use `ArgParser` directly to define flags (`addFlag`) and options (`addOption`).
+*   If building a complex, multi-command CLI (like `git`): Implement `CommandRunner` and extend `Command` for each subcommand.
+*   Define global arguments on the `CommandRunner.argParser` and command-specific arguments on the individual `Command.argParser`.
+*   Catch `UsageException` to gracefully handle invalid arguments and display the automatically generated help text.
+*   **Validate Help Text Accuracy**: Ensure the help text provides all necessary information to run the tool. If the help text references a compiled executable name, and the user needs to add it to their PATH to run it that way, provide clear instructions on how to do so in the help text or description.
+
+## Execution & Error Handling
+
+Leverage the `io` and `stack_trace` packages to build robust, production-ready CLI tools.
+
+*   Use the `io` package's `ExitCode` enum to return standard POSIX exit codes (e.g., `ExitCode.success.code`, `ExitCode.usage.code`).
+*   Use `sharedStdIn` from the `io` package if multiple asynchronous listeners need sequential access to standard input.
+*   Wrap the application execution in `Chain.capture()` from the `stack_trace` package to track asynchronous stack chains.
+*   Format output stack traces using `Trace.terse` or `Chain.terse` to strip noisy core library frames and present readable errors to the user.
+*   **Do not swallow exceptions** in lower-level logic or storage classes unless recovery is possible. Let them bubble up or rethrow them so higher-level commands know operations failed.
+*   **Fail fast and with non-zero exit codes**: Ensure operation failures result in descriptive error messages to `stderr` and appropriate non-zero exit codes (e.g., using `exit(1)` or triggering a 64 exit code after a caught `UsageException`).
+
+## Testing CLI Applications
+
+> [!IMPORTANT]
+> **All new commands and significant features must be covered by automated tests.** Manual verification is not sufficient for testing logic. However, manual verification of help text and user experience (UX) is still required to ensure the interface is intuitive and correct.
+
+Use `test_process` and `test_descriptor` to write high-fidelity integration tests for your CLI.
+
+*   Define expected filesystem states using `test_descriptor` (`d.dir`, `d.file`).
+*   Create the mock filesystem before execution using `await d.Descriptor.create()`.
+*   Spawn the CLI process using `TestProcess.start('dart', ['run', 'bin/cli.dart', ...args])`.
+*   Validate standard output and error streams using `StreamQueue` matchers (e.g., `emitsThrough`, `emits`).
+*   Assert the final exit code using `await process.shouldExit(0)`.
+*   Validate resulting filesystem mutations using `await d.Descriptor.validate()`.
+
+## Compilation & Distribution
+
+Select the appropriate compilation target based on your distribution requirements.
+
+*   **If testing locally during development:** Use `dart run bin/cli.dart`. This uses the JIT compiler for rapid iteration.
+*   **If bundling code assets and dynamic libraries:** Use `dart build cli`. This runs build hooks and outputs to `build/cli/_/bundle/`.
+*   **If distributing a standalone native executable:** Use `dart compile exe bin/cli.dart -o <output_path>`. This bundles the Dart runtime and machine code into a single file.
+*   **If distributing multiple apps with strict disk space limits:** Use `dart compile aot-snapshot bin/cli.dart`. Run the resulting `.aot` file using `dartaotruntime`.
+
+<details>
+<summary>Cross-Compilation Targets (Linux Only)</summary>
+
+Dart supports cross-compiling to Linux from macOS, Windows, or Linux hosts.
+Use the `--target-os` and `--target-arch` flags with `dart compile exe` or `dart compile aot-snapshot`.
+
+*   `--target-os=linux` (Only Linux is currently supported as a cross-compilation target)
+*   `--target-arch=arm64` (64-bit ARM)
+*   `--target-arch=x64` (x86-64)
+*   `--target-arch=arm` (32-bit ARM)
+*   `--target-arch=riscv64` (64-bit RISC-V)
+
+Example: `dart compile exe --target-os=linux --target-arch=arm64 bin/cli.dart`
+</details>
+
+## Workflows
+
+### Task Progress: Implement a New CLI Command
+- [ ] Create a new class extending `Command` in `lib/src/commands/`.
+- [ ] Define the `name` and `description` properties.
+- [ ] Register command-specific flags in the constructor using `argParser.addFlag()` or `argParser.addOption()`.
+- [ ] Implement the `run()` method with the core logic.
+- [ ] Register the new command in the `CommandRunner` instance in `bin/cli.dart` using `addCommand()`.
+- [ ] Create tests for the new command in the `test/` directory using `test_process` or standard tests.
+- [ ] Run validator -> Execute `dart run bin/cli.dart help <command_name>` to verify help text generation.
+- [ ] Verify final UX: Compile the application using `dart compile exe` and run the resulting executable to verify the target user experience (e.g., `./bin/cli <command>`).
+
+### Task Progress: Compile and Release Native Executable
+- [ ] Run validator -> Execute `dart format . --set-exit-if-changed` to ensure code formatting.
+- [ ] Run validator -> Execute `dart analyze` to ensure no static analysis errors.
+- [ ] Run validator -> Execute `dart test` to pass all integration tests.
+- [ ] Compile for host OS: `dart compile exe bin/cli.dart -o build/cli-host`
+- [ ] Compile for Linux (if host is macOS/Windows): `dart compile exe --target-os=linux --target-arch=x64 bin/cli.dart -o build/cli-linux-x64`
+
+## Examples
+
+### Example: CommandRunner Implementation
+
+```dart
+import 'dart:io';
+import 'package:args/command_runner.dart';
+import 'package:stack_trace/stack_trace.dart';
+
+class CommitCommand extends Command {
+  @override
+  final String name = 'commit';
+  @override
+  final String description = 'Record changes to the repository.';
+
+  CommitCommand() {
+    argParser.addFlag('all', abbr: 'a', help: 'Commit all changed files.');
+  }
+
+  @override
+  Future<void> run() async {
+    final commitAll = argResults?['all'] as bool? ?? false;
+    print('Committing... (All: $commitAll)');
+  }
+}
+
+void main(List<String> args) {
+  Chain.capture(() async {
+    final runner = CommandRunner('dgit', 'Distributed version control.')
+      ..addCommand(CommitCommand());
+
+    await runner.run(args);
+  }, onError: (error, chain) {
+    if (error is UsageException) {
+      stderr.writeln(error.message);
+      stderr.writeln(error.usage);
+      exit(64); // ExitCode.usage.code
+    } else {
+      stderr.writeln('Fatal error: $error');
+      stderr.writeln(chain.terse);
+      exit(1);
+    }
+  });
+}
+```
+
+### Example: Integration Testing with Subprocesses
+
+```dart
+import 'package:test/test.dart';
+import 'package:test_process/test_process.dart';
+import 'package:test_descriptor/test_descriptor.dart' as d;
+
+void main() {
+  test('CLI formats output correctly and modifies filesystem', () async {
+    // 1. Setup mock filesystem
+    await d.dir('project', [
+      d.file('config.json', '{"key": "value"}')
+    ]).create();
+
+    // 2. Spawn the CLI process
+    final process = await TestProcess.start(
+      'dart',
+      ['run', 'bin/cli.dart', 'process', '--path', '${d.sandbox}/project']
+    );
+
+    // 3. Validate stdout stream
+    await expectLater(process.stdout, emitsThrough('Processing complete.'));
+
+    // 4. Validate exit code
+    await process.shouldExit(0);
+
+    // 5. Validate filesystem mutations
+    await d.dir('project', [
+      d.file('config.json', '{"key": "value"}'),
+      d.file('output.log', 'Success')
+    ]).validate();
+  });
+}
+```

package/template/.opencode/skills/dart-collect-coverage/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: dart-collect-coverage
+description: Collect coverage using the coverage packge and create an LCOV report
+metadata:
+  model: models/gemini-3.1-pro-preview
+  last_modified: Fri, 24 Apr 2026 15:14:32 GMT
+---
+# Implementing Dart and Flutter Test Coverage
+
+## Contents
+- [Testing Fundamentals](#testing-fundamentals)
+- [Coverage Directives](#coverage-directives)
+- [Workflow: Configuring and Generating Coverage Reports](#workflow-configuring-and-generating-coverage-reports)
+- [Workflow: Advanced Manual Coverage Collection](#workflow-advanced-manual-coverage-collection)
+- [Examples](#examples)
+
+## Testing Fundamentals
+
+Structure your test suites using the standard Dart testing paradigms. Use `package:test` for Dart projects and `flutter_test` for Flutter projects.
+
+- **Unit Tests:** Verify individual functions, methods, or classes.
+- **Component/Widget Tests:** Verify component behavior, layout, and interaction using mock objects (`package:mockito`).
+- **Integration Tests:** Verify entire app flows on simulated or real devices.
+
+## Coverage Directives
+
+Exclude specific lines, blocks, or entire files from coverage metrics using inline comments. Pass the `--check-ignore` flag during formatting to enforce these directives.
+
+- Ignore a single line: `// coverage:ignore-line`
+- Ignore a block of code: `// coverage:ignore-start` and `// coverage:ignore-end`
+- Ignore an entire file: `// coverage:ignore-file`
+
+## Workflow: Configuring and Generating Coverage Reports
+
+Follow this sequential workflow to add the coverage package, execute tests, and generate an LCOV report.
+
+**Task Progress Checklist:**
+- [ ] 1. Add `coverage` as a `dev_dependency`.
+- [ ] 2. Execute the automated coverage script.
+- [ ] 3. Validate the LCOV output.
+
+### 1. Add Dependencies
+Add the `coverage` package as a `dev_dependency` to your project. Do not add it to standard dependencies.
+
+If working in a standard Dart project:
+```bash
+dart pub add dev:coverage
+```
+
+If working in a Flutter project:
+```bash
+flutter pub add dev:coverage
+```
+
+### 2. Collect Coverage and Generate LCOV
+Use the bundled `test_with_coverage` script. This script automatically runs all tests, collects the JSON coverage data from the Dart VM, and formats it into an LCOV report.
+
+```bash
+dart run coverage:test_with_coverage
+```
+*Note: If working within a Dart workspace (monorepo), specify the test directories explicitly (e.g., `dart run coverage:test_with_coverage -- pkgs/foo/test pkgs/bar/test`).*
+
+### 3. Feedback Loop: Validate Output
+**Run validator -> review errors -> fix:**
+1. Verify that the `coverage/` directory was created in the project root.
+2. Ensure `coverage/coverage.json` (raw data) and `coverage/lcov.info` (formatted report) exist.
+3. If coverage is missing for specific files, ensure they are imported and executed by your test files, or add `// coverage:ignore-file` if they are intentionally excluded.
+
+## Workflow: Advanced Manual Coverage Collection
+
+If you require granular control over the VM service, isolate pausing, or need branch/function-level coverage, use the manual collection workflow.
+
+**Task Progress Checklist:**
+- [ ] 1. Run tests with VM service enabled.
+- [ ] 2. Collect raw JSON coverage.
+- [ ] 3. Format JSON to LCOV.
+
+### 1. Run Tests with VM Service
+Execute tests while pausing isolates on exit and exposing the VM service on a specific port (e.g., 8181).
+
+```bash
+dart run --pause-isolates-on-exit --disable-service-auth-codes --enable-vm-service=8181 test &
+```
+
+### 2. Collect Raw Coverage
+Extract the coverage data from the running VM service and output it to a JSON file.
+
+```bash
+dart run coverage:collect_coverage --wait-paused --uri=http://127.0.0.1:8181/ -o coverage/coverage.json --resume-isolates
+```
+*Optional: Append `--function-coverage` and `--branch-coverage` to gather deeper metrics (requires Dart VM 2.17.0+).*
+
+### 3. Format to LCOV
+Convert the raw JSON data into the standard LCOV format.
+
+```bash
+dart run coverage:format_coverage --packages=.dart_tool/package_config.json --lcov -i coverage/coverage.json -o coverage/lcov.info --check-ignore
+```
+
+## Examples
+
+### Example: `pubspec.yaml` Configuration
+Ensure your `pubspec.yaml` reflects the `coverage` package strictly under `dev_dependencies`.
+
+```yaml
+name: my_dart_app
+environment:
+  sdk: ^3.0.0
+
+dependencies:
+  path: ^1.8.0
+
+dev_dependencies:
+  test: ^1.24.0
+  coverage: ^1.15.0
+```
+
+### Example: Applying Ignore Directives
+Use ignore directives to prevent generated code or untestable edge cases from lowering coverage scores.
+
+```dart
+// coverage:ignore-file
+import 'package:meta/meta.dart';
+
+class SystemConfig {
+  final String env;
+
+  SystemConfig(this.env);
+
+  // coverage:ignore-start
+  void legacyInit() {
+    print('Deprecated initialization');
+  }
+  // coverage:ignore-end
+
+  bool isProduction() {
+    if (env == 'prod') return true;
+    return false; // coverage:ignore-line
+  }
+}
+```

package/template/.opencode/skills/dart-fix-runtime-errors/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: dart-fix-runtime-errors
+description: Uses get_runtime_errors and lsp to fetch an active stack trace, locate the failing line, apply a fix, and verify resolution via hot_reload.
+metadata:
+  model: models/gemini-3.1-pro-preview
+  last_modified: Fri, 24 Apr 2026 15:13:22 GMT
+---
+# Resolving Dart Static Analysis Errors
+
+## Contents
+- [Core Concepts & Guidelines](#core-concepts--guidelines)
+  - [Type System & Soundness](#type-system--soundness)
+  - [Null Safety](#null-safety)
+  - [Error Handling](#error-handling)
+- [Workflows](#workflows)
+  - [Workflow: Static Analysis Resolution](#workflow-static-analysis-resolution)
+- [Examples](#examples)
+
+## Core Concepts & Guidelines
+
+### Type System & Soundness
+Enforce Dart's sound type system to prevent runtime invalid states.
+
+*   **Method Overrides:** Maintain sound return types (covariant) and parameter types (contravariant). Never tighten a parameter type in a subclass unless explicitly marked with the `covariant` keyword.
+*   **Generics & Collections:** Add explicit type annotations to generic classes (e.g., `List<T>`, `Map<K, V>`). Never assign a `List<dynamic>` to a typed list (e.g., `List<Cat>`).
+*   **Downcasting:** Avoid implicit downcasts from `dynamic`. Use explicit casts (e.g., `as List<Cat>`) when necessary, but ensure the underlying runtime type matches to prevent `TypeError` exceptions.
+*   **Strict Casts:** Enable `strict-casts: true` in `analysis_options.yaml` under `analyzer: language:` to force explicit casting and catch implicit downcast errors at compile time.
+
+### Null Safety
+Eliminate static errors related to null safety by correctly managing variable initialization and nullability.
+
+*   **Modifiers:** Apply `?` for nullable types, `!` for null assertions, and `required` for named parameters that cannot be null.
+*   **Late Initialization:** Use the `late` keyword for non-nullable variables guaranteed to be initialized before use. Apply this specifically to top-level or instance variables where Dart's control flow analysis cannot definitively prove initialization.
+*   **Wildcards:** Use the `_` wildcard variable (Dart 3.7+) for non-binding local variables or parameters to avoid unused variable warnings.
+
+### Error Handling
+Distinguish between recoverable exceptions and unrecoverable errors.
+
+*   **Catching:** Catch `Exception` subtypes for recoverable failures.
+*   **Errors:** Never explicitly catch `Error` or its subtypes (e.g., `TypeError`, `ArgumentError`). Errors indicate programming bugs that must be fixed, not caught. Enforce this by enabling the `avoid_catching_errors` linter rule.
+*   **Rethrowing:** Use `rethrow` inside a `catch` block to propagate an exception while preserving its original stack trace.
+
+## Workflows
+
+### Workflow: Static Analysis Resolution
+
+Use this sequential workflow to identify, fix, and verify static analysis errors in a Dart project. Copy the checklist to track your progress.
+
+**Task Progress:**
+- [ ] 1. Run static analyzer.
+- [ ] 2. Apply automated fixes.
+- [ ] 3. Resolve remaining errors manually.
+- [ ] 4. Verify fixes (Feedback Loop).
+
+**1. Run static analyzer**
+Execute the Dart analyzer to identify all static errors in the target directory or file.
+```bash
+dart analyze . --fatal-infos
+```
+
+**2. Apply automated fixes**
+Use the `dart fix` tool to automatically resolve standard linting and analysis issues.
+```bash
+# Preview changes
+dart fix --dry-run
+# Apply changes
+dart fix --apply
+```
+
+**3. Resolve remaining errors manually**
+Review the remaining analyzer output and apply conditional logic based on the error type:
+
+*   **If the error is a Null Safety issue (e.g., "Property cannot be accessed on a nullable receiver"):**
+    *   Verify if the variable can logically be null.
+    *   If yes, use optional chaining (`?.`) or provide a fallback (`??`).
+    *   If no, and initialization is guaranteed elsewhere, mark the declaration with `late`.
+*   **If the error is a Type Mismatch (e.g., "The argument type 'List<dynamic>' can't be assigned..."):**
+    *   Trace the variable's initialization.
+    *   Add explicit generic type annotations to the instantiation (e.g., `<int>[]` instead of `[]`).
+*   **If the error is an Invalid Override (e.g., "The parameter type doesn't match the overridden method"):**
+    *   Widen the parameter type to match the superclass, OR
+    *   Add the `covariant` keyword to the parameter if tightening the type is intentionally required by the domain logic.
+
+**4. Verify fixes (Feedback Loop)**
+Run the validator. Review errors. Fix.
+```bash
+dart analyze .
+dart test
+```
+*   **If `dart analyze` reports errors:** Return to Step 3.
+*   **If `dart test` fails with a `TypeError`:** You have introduced an invalid explicit cast (`as T`) or accessed an uninitialized `late` variable. Locate the runtime failure and correct the type hierarchy or initialization order.
+
+## Examples
+
+### Example: Fixing Dynamic List Assignments
+**Input (Fails Static Analysis):**
+```dart
+void printInts(List<int> a) => print(a);
+
+void main() {
+  final list = []; // Inferred as List<dynamic>
+  list.add(1);
+  list.add(2);
+  printInts(list); // Error: List<dynamic> can't be assigned to List<int>
+}
+```
+
+**Output (Passes Static Analysis):**
+```dart
+void printInts(List<int> a) => print(a);
+
+void main() {
+  final list = <int>[]; // Explicitly typed
+  list.add(1);
+  list.add(2);
+  printInts(list);
+}
+```
+
+### Example: Fixing Method Overrides (Contravariance)
+**Input (Fails Static Analysis):**
+```dart
+class Animal {
+  void chase(Animal a) {}
+}
+
+class Cat extends Animal {
+  @override
+  void chase(Mouse a) {} // Error: Tightening parameter type
+}
+```
+
+**Output (Passes Static Analysis):**
+```dart
+class Animal {
+  void chase(Animal a) {}
+}
+
+class Cat extends Animal {
+  @override
+  void chase(covariant Mouse a) {} // Explicitly marked covariant
+}
+```
+
+### Example: Fixing Null Safety with `late`
+**Input (Fails Static Analysis):**
+```dart
+class Thermometer {
+  String temperature; // Error: Non-nullable instance field must be initialized
+
+  void read() {
+    temperature = '20C';
+  }
+}
+```
+
+**Output (Passes Static Analysis):**
+```dart
+class Thermometer {
+  late String temperature; // Defers initialization check to runtime
+
+  void read() {
+    temperature = '20C';
+  }
+}
+```