@bdayadev/flutter-ultra-mcp 1.12.0 → 1.14.0

package/skills/fix-layout-issues/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: fix-layout-issues
 description: Fixes Flutter layout errors (overflows, unbounded constraints) using Dart and Flutter MCP tools. Use when addressing "RenderFlex overflowed", "Vertical viewport was given unbounded height", or similar layout issues.
+  last_modified: Tue, 21 Apr 2026 19:45:59 GMT
 ---
 
 # Resolving Flutter Layout Errors
@@ -13,35 +14,40 @@ description: Fixes Flutter layout errors (overflows, unbounded constraints) usin
 
 ## Constraint Violation Diagnostics
 
-Flutter layout operates on: **Constraints go down. Sizes go up. Parent sets position.** Layout errors occur when this negotiation fails.
+Flutter layout operates on a strict rule: **Constraints go down. Sizes go up. Parent sets position.** Layout errors occur when this negotiation fails, typically due to unbounded constraints or unconstrained children.
 
-- **"Vertical viewport was given unbounded height"**: Scrollable widget (`ListView`, `GridView`) inside unconstrained vertical parent (`Column`).
-- **"An InputDecorator...cannot have an unbounded width"**: `TextField` inside unconstrained horizontal parent (`Row`).
-- **"RenderFlex overflowed"**: Child of `Row` or `Column` requests more size than available. Yellow and black warning stripes.
-- **"Incorrect use of ParentData widget"**: `ParentDataWidget` not a direct descendant of required ancestor (e.g., `Expanded` outside a `Flex`).
-- **"RenderBox was not laid out"**: Cascading side-effect. Look further up the stack trace for the primary violation.
+Diagnose layout failures using the following error signatures:
+
+- **"Vertical viewport was given unbounded height"**: Triggered when a scrollable widget (`ListView`, `GridView`) is placed inside an unconstrained vertical parent (`Column`). The parent provides infinite height, and the child attempts to expand infinitely.
+- **"An InputDecorator...cannot have an unbounded width"**: Triggered when a `TextField` or `TextFormField` is placed inside an unconstrained horizontal parent (`Row`). The text field attempts to determine its width based on infinite available space.
+- **"RenderFlex overflowed"**: Triggered when a child of a `Row` or `Column` requests a size larger than the parent's allocated constraints. Visually indicated by yellow and black warning stripes.
+- **"Incorrect use of ParentData widget"**: Triggered when a `ParentDataWidget` is not a direct descendant of its required ancestor. (e.g., `Expanded` outside a `Flex`, `Positioned` outside a `Stack`).
+- **"RenderBox was not laid out"**: A cascading side-effect error. Ignore this and look further up the stack trace for the primary constraint violation (usually an unbounded height/width error).
 
 ## Layout Error Resolution Workflow
 
+Copy and use this checklist to systematically resolve layout constraint violations.
+
 ### Task Progress
 
-- [ ] Run the application in debug mode to capture the exception.
-- [ ] Identify the primary error message (ignore cascading errors).
-- [ ] Apply the conditional fix:
-  - **"Unbounded height"**: Wrap scrollable child in `Expanded` or `SizedBox`.
-  - **"Unbounded width"**: Wrap `TextField` in `Expanded` or `Flexible`.
-  - **"RenderFlex overflowed"**: Wrap overflowing child in `Expanded` or `Flexible`.
-  - **"Incorrect ParentData"**: Move the widget to be a direct child of its required parent.
+- [ ] Run the application in debug mode to capture the exact layout exception in the console.
+- [ ] Identify the primary error message (ignore cascading "RenderBox was not laid out" errors).
+- [ ] Apply the conditional fix based on the specific error type:
+  - **If "Vertical viewport was given unbounded height"**: Wrap the scrollable child (`ListView`, `GridView`) in an `Expanded` widget to consume remaining space, or wrap it in a `SizedBox` to provide an absolute height constraint.
+  - **If "An InputDecorator...cannot have an unbounded width"**: Wrap the `TextField` or `TextFormField` in an `Expanded` or `Flexible` widget.
+  - **If "RenderFlex overflowed"**: Constrain the overflowing child by wrapping it in an `Expanded` widget (to force it to fit) or a `Flexible` widget (to allow it to be smaller than the allocated space).
+  - **If "Incorrect use of ParentData widget"**: Move the `ParentDataWidget` to be a direct child of its required parent. Ensure `Expanded`/`Flexible` are direct children of `Row`/`Column`/`Flex`. Ensure `Positioned` is a direct child of `Stack`.
 - [ ] Execute Flutter hot reload.
-- [ ] Verify the error screen or overflow stripes are resolved. Repeat if new errors appear.
+- [ ] Run validator -> review errors -> fix: Inspect the UI to verify the red/grey error screen or yellow/black overflow stripes are resolved. If new layout errors appear, repeat the workflow.
 
 ## Examples
 
 ### Fixing Unbounded Height (ListView in Column)
 
-**Before (Error):**
+**Input (Error State):**
 
 ```dart
+// Throws "Vertical viewport was given unbounded height"
 Column(
   children: <Widget>[
     const Text('Header'),
@@ -55,9 +61,10 @@ Column(
 )
 ```
 
-**After (Fixed):**
+**Output (Resolved State):**
 
 ```dart
+// Wrap ListView in Expanded to constrain its height to the remaining Column space
 Column(
   children: <Widget>[
     const Text('Header'),
@@ -75,15 +82,59 @@ Column(
 
 ### Fixing Unbounded Width (TextField in Row)
 
-**Before:** `Row(children: [Icon(Icons.search), TextField()])`
+**Input (Error State):**
+
+```dart
+// Throws "An InputDecorator...cannot have an unbounded width"
+Row(
+  children: [
+    const Icon(Icons.search),
+    TextField(),
+  ],
+)
+```
 
-**After:** `Row(children: [Icon(Icons.search), Expanded(child: TextField())])`
+**Output (Resolved State):**
+
+```dart
+// Wrap TextField in Expanded to constrain its width to the remaining Row space
+Row(
+  children: [
+    const Icon(Icons.search),
+    Expanded(
+      child: TextField(),
+    ),
+  ],
+)
+```
 
 ### Fixing RenderFlex Overflow
 
-**Before:** `Row(children: [Icon(Icons.info), Text('Very long text...')])`
+**Input (Error State):**
+
+```dart
+// Throws "A RenderFlex overflowed by X pixels on the right"
+Row(
+  children: [
+    const Icon(Icons.info),
+    const Text('This is a very long text string that will definitely overflow the available screen width and cause a RenderFlex error.'),
+  ],
+)
+```
+
+**Output (Resolved State):**
 
-**After:** `Row(children: [Icon(Icons.info), Expanded(child: Text('Very long text...'))])`
+```dart
+// Wrap the Text widget in Expanded to force it to wrap within the available constraints
+Row(
+  children: [
+    const Icon(Icons.info),
+    Expanded(
+      child: const Text('This is a very long text string that will definitely overflow the available screen width and cause a RenderFlex error.'),
+    ),
+  ],
+)
+```
 
 ## Flutter Ultra Integration
 

package/skills/fix-runtime-errors/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: 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.
+  last_modified: Fri, 24 Apr 2026 15:13:22 GMT
 ---
 
 # Resolving Dart Static Analysis Errors
@@ -8,7 +9,11 @@ description: Uses get_runtime_errors and lsp to fetch an active stack trace, loc
 ## 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
@@ -18,30 +23,32 @@ description: Uses get_runtime_errors and lsp to fetch an active stack trace, loc
 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.
+- **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.
+- **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.
-- **Wildcards:** Use the `_` wildcard variable (Dart 3.7+) for non-binding local variables or parameters.
+- **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.
+- **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.
@@ -50,36 +57,52 @@ Distinguish between recoverable exceptions and unrecoverable errors.
 - [ ] 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**
-
-- **If Null Safety issue:** Verify if the variable can logically be null. Use `?.` or `??` if yes, `late` if initialization is guaranteed elsewhere.
-- **If Type Mismatch:** Add explicit generic type annotations to the instantiation.
-- **If Invalid Override:** Widen the parameter type or add `covariant`.
+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
 
-### Fixing Dynamic List Assignments
+### Example: Fixing Dynamic List Assignments
 
-**Input (Fails):**
+**Input (Fails Static Analysis):**
 
 ```dart
 void printInts(List<int> a) => print(a);
@@ -87,11 +110,12 @@ void printInts(List<int> a) => print(a);
 void main() {
   final list = []; // Inferred as List<dynamic>
   list.add(1);
-  printInts(list); // Error
+  list.add(2);
+  printInts(list); // Error: List<dynamic> can't be assigned to List<int>
 }
 ```
 
-**Output (Passes):**
+**Output (Passes Static Analysis):**
 
 ```dart
 void printInts(List<int> a) => print(a);
@@ -99,27 +123,62 @@ void printInts(List<int> a) => print(a);
 void main() {
   final list = <int>[]; // Explicitly typed
   list.add(1);
+  list.add(2);
   printInts(list);
 }
 ```
 
-### Fixing Null Safety with `late`
+### 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):**
+**Input (Fails Static Analysis):**
 
 ```dart
 class Thermometer {
-  String temperature; // Error: Non-nullable must be initialized
-  void read() { temperature = '20C'; }
+  String temperature; // Error: Non-nullable instance field must be initialized
+
+  void read() {
+    temperature = '20C';
+  }
 }
 ```
 
-**Output (Passes):**
+**Output (Passes Static Analysis):**
 
 ```dart
 class Thermometer {
-  late String temperature;
-  void read() { temperature = '20C'; }
+  late String temperature; // Defers initialization check to runtime
+
+  void read() {
+    temperature = '20C';
+  }
 }
 ```
 

package/skills/generate-test-mocks/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: generate-test-mocks
 description: Define and generate mock objects for external dependencies using `package:mockito` and `build_runner`. Use when unit testing classes that depend on complex external services like APIs or databases.
+  last_modified: Fri, 24 Apr 2026 15:13:58 GMT
 ---
 
 # Testing and Mocking Dart Applications
@@ -16,10 +17,11 @@ description: Define and generate mock objects for external dependencies using `p
 
 ## Structuring Code for Testability
 
-Design Dart classes to support dependency injection. Isolate complex external dependencies so they can be replaced with mock objects during testing.
+Design Dart classes to support dependency injection. Isolate complex external dependencies (like API clients or databases) so they can be replaced with mock objects during testing.
 
 - Inject external services (e.g., `http.Client`) through class constructors.
 - Represent URLs strictly as `Uri` objects using `Uri.parse(string)`.
+- Utilize Dart's object-oriented features (classes, mixins) to define clear interfaces for external interactions.
 
 ## Managing Dependencies
 
@@ -27,33 +29,38 @@ Configure the `pubspec.yaml` file with the necessary testing and code generation
 
 - Add runtime dependencies (e.g., `package:http`) using `dart pub add http`.
 - Add testing dependencies using `dart pub add dev:test dev:mockito dev:build_runner`.
-- Import HTTP libraries with a prefix: `import 'package:http/http.dart' as http;`.
+- Import HTTP libraries with a prefix to avoid namespace collisions: `import 'package:http/http.dart' as http;`.
 
 ## Generating Mocks
 
-Use `package:mockito` and `build_runner` to automatically generate mock classes.
+Use `package:mockito` and `build_runner` to automatically generate mock classes for fixed scenarios and behavior verification.
 
-- Always use the `@GenerateNiceMocks` annotation (preferable to `@GenerateMocks`).
+- Always use the `@GenerateNiceMocks` annotation (preferable to `@GenerateMocks` to avoid missing stub exceptions).
 - Place the annotation in the test file, passing a list of `MockSpec<Type>()` objects.
 - Import the generated file using the `.mocks.dart` extension.
 - Execute `build_runner` to generate the mock files: `dart run build_runner build`.
 
 ## Implementing Unit Tests
 
-Isolate the system under test using the generated mock objects.
+Isolate the system under test using the generated mock objects. Use `package:test` to structure the test suite.
 
-- **Stubbing:** Use `when(mock.method()).thenReturn(value)` for synchronous methods.
-- **CRITICAL:** Always use `thenAnswer((_) async => value)` for methods returning a `Future` or `Stream`. Never use `thenReturn` for asynchronous returns.
-- **Verification:** Use `verify(mock.method()).called(1)` to check exact invocation counts.
+- **Stubbing:** Configure mock behavior before interacting with the system under test.
+  - Use `when(mock.method()).thenReturn(value)` for synchronous methods.
+  - **CRITICAL:** Always use `thenAnswer((_) async => value)` for methods returning a `Future` or `Stream`. Never use `thenReturn` for asynchronous returns.
+- **Verification:** Assert that the system under test interacted with the mock object correctly.
+  - Use `verify(mock.method()).called(1)` to check exact invocation counts.
+  - Use argument matchers like `any`, `anyNamed`, or `captureAny` for flexible verification.
 
 ## Workflow: Creating and Running Mocked Tests
 
+Use the following checklist to implement and verify mocked unit tests.
+
 ### Task Progress
 
-- [ ] 1. Identify the external dependency to mock.
+- [ ] 1. Identify the external dependency to mock (e.g., `http.Client`).
 - [ ] 2. Inject the dependency into the target class constructor.
-- [ ] 3. Create a test file and add `@GenerateNiceMocks([MockSpec<Dependency>()])`.
-- [ ] 4. Add the import directive for the generated `.mocks.dart` file.
+- [ ] 3. Create a test file (e.g., `target_test.dart`) and add `@GenerateNiceMocks([MockSpec<Dependency>()])`.
+- [ ] 4. Add the `part` or `import` directive for the generated `.mocks.dart` file.
 - [ ] 5. Run `dart run build_runner build` to generate the mock classes.
 - [ ] 6. Write the test cases using `group()` and `test()`.
 - [ ] 7. Stub required behaviors using `when()`.
@@ -61,11 +68,23 @@ Isolate the system under test using the generated mock objects.
 - [ ] 9. Verify interactions using `verify()` and assert outcomes using `expect()`.
 - [ ] 10. Run the test suite using `dart test`.
 
+### Feedback Loop: Test Failures
+
+If tests fail or `build_runner` encounters errors:
+
+1. **Run validator:** Execute `dart test` or `dart run build_runner build`.
+2. **Review errors:** Check for missing stubs, mismatched argument matchers, or syntax errors in the generated files.
+3. **Fix:**
+   - If a mock method throws an unexpected null error, ensure you used `@GenerateNiceMocks`.
+   - If an async stub throws an `ArgumentError`, change `thenReturn` to `thenAnswer`.
+   - If `build_runner` fails, ensure the `.mocks.dart` import matches the file name exactly.
+4. Repeat until all tests pass.
+
 ## Examples
 
 ### High-Fidelity Mocking and Testing Example
 
-**System Under Test (`lib/api_service.dart`):**
+**1. System Under Test (`lib/api_service.dart`)**
 
 ```dart
 import 'dart:convert';
@@ -73,11 +92,13 @@ import 'package:http/http.dart' as http;
 
 class ApiService {
   final http.Client client;
+
   ApiService(this.client);
 
   Future<String> fetchData(String urlString) async {
     final uri = Uri.parse(urlString);
     final response = await client.get(uri);
+
     if (response.statusCode == 200) {
       return jsonDecode(response.body)['data'];
     } else {
@@ -87,7 +108,7 @@ class ApiService {
 }
 ```
 
-**Test Implementation (`test/api_service_test.dart`):**
+**2. Test Implementation (`test/api_service_test.dart`)**
 
 ```dart
 import 'package:test/test.dart';
@@ -96,6 +117,7 @@ import 'package:mockito/mockito.dart';
 import 'package:http/http.dart' as http;
 import 'package:my_app/api_service.dart';
 
+// Generate the mock class for http.Client
 @GenerateNiceMocks([MockSpec<http.Client>()])
 import 'api_service_test.mocks.dart';
 
@@ -110,20 +132,28 @@ void main() {
     });
 
     test('returns data if the http call completes successfully', () async {
+      // Arrange: Stub the async HTTP GET request using thenAnswer
       when(mockHttpClient.get(any)).thenAnswer(
         (_) async => http.Response('{"data": "Success"}', 200),
       );
 
+      // Act
       final result = await apiService.fetchData('https://api.example.com/data');
+
+      // Assert
       expect(result, 'Success');
+
+      // Verify the mock was called with the correct Uri
       verify(mockHttpClient.get(Uri.parse('https://api.example.com/data'))).called(1);
     });
 
     test('throws an exception if the http call completes with an error', () {
+      // Arrange
       when(mockHttpClient.get(any)).thenAnswer(
         (_) async => http.Response('Not Found', 404),
       );
 
+      // Act & Assert
       expect(
         apiService.fetchData('https://api.example.com/data'),
         throwsException,

package/skills/implement-json-serialization/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: implement-json-serialization
 description: Create model classes with `fromJson` and `toJson` methods using `dart:convert`. Use when manually mapping JSON keys to class properties for simple data structures.
+  last_modified: Tue, 21 Apr 2026 21:44:50 GMT
 ---
 
 # Serializing JSON Manually in Flutter
@@ -14,36 +15,52 @@ description: Create model classes with `fromJson` and `toJson` methods using `da
 
 ## Core Guidelines
 
-- **Import `dart:convert`**: Use `jsonEncode` and `jsonDecode`.
-- **Enforce Type Safety**: Cast `jsonDecode()` result to `Map<String, dynamic>` or `List<dynamic>`.
-- **Encapsulate Logic**: Define `fromJson` factory constructor and `toJson` method in model classes.
-- **Handle Background Parsing**: If parsing takes >16ms, use `compute()` to prevent UI jank.
-- **Throw on Failure**: Throw an exception on non-success HTTP status codes. Do not return `null`.
+- **Import `dart:convert`**: Utilize Flutter's built-in `dart:convert` library for manual JSON encoding (`jsonEncode`) and decoding (`jsonDecode`).
+- **Enforce Type Safety**: Always cast the `dynamic` result of `jsonDecode()` to the expected type, typically `Map<String, dynamic>` for objects or `List<dynamic>` for arrays.
+- **Encapsulate Serialization Logic**: Define plain model classes containing properties corresponding to the JSON structure. Implement a `fromJson` factory constructor and a `toJson` method within the model.
+- **Handle Background Parsing**: If parsing large JSON documents (execution time > 16ms), offload the parsing logic to a separate isolate using Flutter's `compute()` function to prevent UI jank.
+- **Throw Exceptions on Failure**: When handling HTTP responses, throw an exception if the status code is not successful (e.g., not 200 OK or 201 Created). Do not return `null`.
 
 ## Workflow: Implementing a Serializable Model
 
+Use this checklist to implement manual JSON serialization for a data model.
+
 **Task Progress:**
 
 - [ ] Define the plain model class with `final` properties.
-- [ ] Implement `factory Model.fromJson(Map<String, dynamic> json)`.
-- [ ] Implement `Map<String, dynamic> toJson()`.
-- [ ] Write unit tests for both methods.
+- [ ] Implement the `factory Model.fromJson(Map<String, dynamic> json)` constructor.
+- [ ] Implement the `Map<String, dynamic> toJson()` method.
+- [ ] Write unit tests for both serialization methods.
 - [ ] Run validator -> review type mismatch errors -> fix casting logic.
 
+1. **Define the Model**: Create a class with properties matching the JSON keys.
+2. **Implement `fromJson`**: Extract values from the `Map` and cast them to the appropriate Dart types. Use pattern matching or explicit casting.
+3. **Implement `toJson`**: Return a `Map<String, dynamic>` mapping the class properties back to their JSON string keys.
+4. **Validate**: Execute unit tests to ensure type safety, autocompletion, and compile-time exception handling function correctly.
+
 ## Workflow: Fetching and Parsing JSON
 
+Use this conditional workflow when retrieving and parsing JSON from a network request.
+
 **Task Progress:**
 
 - [ ] Execute the HTTP request.
 - [ ] Validate the response status code.
-- [ ] Determine parsing strategy:
-  - **Small payload**: Parse synchronously on the main thread.
-  - **Large payload**: Use `compute(parseFunction, response.body)`.
+- [ ] Determine parsing strategy (Synchronous vs. Isolate).
 - [ ] Decode and map the JSON to the model.
 
+1. **Execute Request**: Use the `http` package to perform the network call.
+2. **Validate Response**:
+   - If `response.statusCode == 200` (or 201 for POST), proceed to parsing.
+   - If the status code indicates failure, throw an `Exception`.
+3. **Determine Parsing Strategy**:
+   - If parsing a **small payload** (e.g., a single object), parse synchronously on the main thread.
+   - If parsing a **large payload** (e.g., an array of thousands of objects), use `compute(parseFunction, response.body)` to parse in a background isolate.
+4. **Decode and Map**: Pass the decoded JSON to your model's `fromJson` constructor.
+
 ## Examples
 
-### Model Implementation
+### High-Fidelity Model Implementation
 
 ```dart
 import 'dart:convert';
@@ -53,17 +70,59 @@ class User {
   final String name;
   final String email;
 
-  const User({required this.id, required this.name, required this.email});
+  const User({
+    required this.id,
+    required this.name,
+    required this.email,
+  });
 
+  // Factory constructor for deserialization
   factory User.fromJson(Map<String, dynamic> json) {
     return switch (json) {
-      {'id': int id, 'name': String name, 'email': String email} =>
-        User(id: id, name: name, email: email),
+      {
+        'id': int id,
+        'name': String name,
+        'email': String email,
+      } =>
+        User(
+          id: id,
+          name: name,
+          email: email,
+        ),
       _ => throw const FormatException('Failed to load User.'),
     };
   }
 
-  Map<String, dynamic> toJson() => {'id': id, 'name': name, 'email': email};
+  // Method for serialization
+  Map<String, dynamic> toJson() {
+    return {
+      'id': id,
+      'name': name,
+      'email': email,
+    };
+  }
+}
+```
+
+### Synchronous Parsing (Small Payload)
+
+```dart
+import 'dart:convert';
+import 'package:http/http.dart' as http;
+
+Future<User> fetchUser(http.Client client, int userId) async {
+  final response = await client.get(
+    Uri.parse('https://api.example.com/users/$userId'),
+    headers: {'Accept': 'application/json'},
+  );
+
+  if (response.statusCode == 200) {
+    // Decode returns dynamic, cast to Map<String, dynamic>
+    final Map<String, dynamic> jsonMap = jsonDecode(response.body) as Map<String, dynamic>;
+    return User.fromJson(jsonMap);
+  } else {
+    throw Exception('Failed to load user');
+  }
 }
 ```
 
@@ -74,14 +133,20 @@ import 'dart:convert';
 import 'package:flutter/foundation.dart';
 import 'package:http/http.dart' as http;
 
+// Top-level function required for compute()
 List<User> parseUsers(String responseBody) {
   final parsed = (jsonDecode(responseBody) as List<dynamic>).cast<Map<String, dynamic>>();
   return parsed.map<User>((json) => User.fromJson(json)).toList();
 }
 
 Future<List<User>> fetchUsers(http.Client client) async {
-  final response = await client.get(Uri.parse('https://api.example.com/users'));
+  final response = await client.get(
+    Uri.parse('https://api.example.com/users'),
+    headers: {'Accept': 'application/json'},
+  );
+
   if (response.statusCode == 200) {
+    // Offload expensive parsing to a background isolate
     return compute(parseUsers, response.body);
   } else {
     throw Exception('Failed to load users');