update llm instructions

.gemini/code_freshness.md

@@ -1,36 +1,55 @@
-This workflow is performed periodically to maintain code health.
+# Code Health and Style Guide Adherence Log
 
-1.  **Prepare the Log File:**
-    *   Check if a `logs/freshness.md` file exists in the root of the
-        repository.
-    *   If it does not exist, create it and add the following header:
-        ```markdown
-        # Fresh Code Log
+This document tracks the ongoing effort to maintain code health and ensure all samples align with the official Flutter style guide. This workflow is performed periodically by an AI assistant.
 
-        This file tracks sample projects that have not received meaningful code updates in over a year.
+## Workflow
 
-        | Sample Name                        | Last Commit Author | Date of Last Commit | Lines of code updated |
-        |------------------------------------|--------------------|---------------------|-----------------------|
-        ```
+The AI assistant performs the following steps for **each sample project** in the repository:
 
-2.  **Analyze Git History:**
-    *   For each sample project in the monorepo:
-        *   Use `git log` to find the most recent commit to a `.dart`
-            file within that sample's directory that was made by a
-            human (i.e., not a bot). 
-        *   **Example command for a sample in `sample_name/`:**
-            ```bash
-            git log -1 --author='^(?!.*bot).*$' --pretty="format:%an,%ad" -- ./sample_name/**/*.dart
-            ```
-        *   Parse the output to get the author's name and the date of
-            the commit, and keep track of the number of lines of code
-            updated to .dart files in that commit.
-
-3.  **Log code update information:**
-    *   Append a new line to table in the freshness log. 
-    *   **Example entry:**
-        ```markdown
-        | my_awesome_sample | Jane Doe | Tue Aug 1 10:00:00 2024 | 10 lines of code
+1.  **Analyze Git History:**
+    *   Use `git log` to find the most recent commit to a `.dart` file within that sample's directory that was made by a human (i.e., not a bot).
+    *   **Example command for a sample in `sample_name/`:**
+        ```bash
+        git log -1 --author='^(?!.*bot).*$' --pretty="format:%ad" --date=short -- ./sample_name/**/*.dart
         ```
+    *   Parse the output to get the date of the last human commit.
+
+2.  **Analyze the Code:** The assistant reads all the relevant `.dart` files within the selected sample's directory.
+
+3.  **Assess Against Style Guide:** The assistant compares the code against the rules and patterns defined in `llm.md`. The assessment focuses on:
+    *   Code organization and structure.
+    *   Adherence to naming conventions.
+    *   Proper use of Flutter and Dart patterns.
+    *   State management best practices.
+    *   Clarity, readability, and documentation.
+
+4.  **Log Findings:** The assistant creates or updates the log entry for the sample. The log entry must include:
+    *   The sample name.
+    *   The date of the last human commit.
+    *   The date of the AI assessment.
+    *   A summary of the style guide adherence.
+    *   A concrete, actionable list of opportunities for improvement.
+
+---
+
+## Sample Assessments
+
+### sample: `provider_shopper`
+
+*   **Last Human Commit:** 2024-11-20
+*   **Last AI Assessment:** 2025-08-08
+*   **Style Guide Adherence:** Good. The sample generally follows the recommended provider patterns and naming conventions. Documentation is present for most public members.
+*   **Improvement Opportunities:**
+    *   **[Refactor]** In `lib/models/cart.dart`, the `add` method could be simplified using a collection-if in the list literal.
+    *   **[Style]** Some private members in `lib/models/catalog.dart` are missing the leading underscore.
+    *   **[Doc]** The top-level `main` function in `lib/main.dart` is missing a doc comment.
+
+### sample: `animations`
 
-4. **Sort the table by most recent update in reverse chronological order.**
+*   **Last Human Commit:** 2024-05-12
+*   **Last AI Assessment:** 2025-08-08
+*   **Style Guide Adherence:** Fair. The sample effectively demonstrates the animations library, but some older patterns are used. The code could be more readable with modern Dart features.
+*   **Improvement Opportunities:**
+    *   **[Clarity]** In `lib/main.dart`, the `build` method for the main widget is over 300 lines long. It should be broken down into smaller, more manageable private widget classes.
+    *   **[Pattern]** The code uses `Future.then()` in a few places. These should be updated to use `async/await` for better readability.
+    *   **[Naming]** Several variables use abbreviations (e.g., `btn` instead of `button`). These should be renamed for clarity.

llm.md

@@ -1,8 +1,8 @@
 You are an expert Dart and Flutter developer on the Flutter team at Google. Your code must adhere to this style guide.
 
-
 ## Core Philosophy
 
+- **Follow Effective Dart guidelines.**
 - **Optimize for readability**: Write code that is easy to understand and maintain
 - **Write detailed documentation**: Every public API should be well-documented
 - **Keep one source of truth**: Avoid duplicating state across your application
@@ -45,6 +45,10 @@ You are an expert Dart and Flutter developer on the Flutter team at Google. Your
 
 ## Code Organization and Structure
 
+- **Define related classes in the same library.**
+- **For large libraries, group smaller libraries by exporting them in a top-level library.**
+- **Group related libraries in the same folder.**
+
 ### Import Ordering (Strict Dart Convention)
 ```dart
 // 1. Dart core libraries (alphabetically)
@@ -110,6 +114,7 @@ class MyWidget extends StatefulWidget {
 - **Prefer lines 80 characters or fewer** for better readability
 - **Maximum 100 characters for comments** (Flutter team preference)
 - **Always use curly braces** for all flow control statements
+- **Don't add trailing comments**
 
 ```dart
 // Good - always use braces
@@ -259,6 +264,11 @@ bool validateEmail(String email) {
 
 ## Flutter-Specific Patterns
 
+- **Prefer composition over inheritance.**
+- **Avoid large build() methods by creating smaller Widgets with a reusable API.**
+- **Use small, private Widget classes instead of private helper methods that return a Widget.**
+- **Use lazy lists wherever possible using ListView.builder.**
+
 ### Widget Construction
 ```dart
 class CustomCard extends StatelessWidget {
@@ -301,31 +311,24 @@ class CustomCard extends StatelessWidget {
 }
 ```
 
-### State Management Patterns
-```dart
-class CounterNotifier extends ChangeNotifier {
-  int _count = 0;
-  
-  int get count => _count;
-  
-  void increment() {
-    _count++;
-    notifyListeners();
-  }
-  
-  void decrement() {
-    if (_count > 0) {
-      _count--;
-      notifyListeners();
-    }
-  }
-  
-  void reset() {
-    _count = 0;
-    notifyListeners();
-  }
-}
-```
+## State Management
+- **Don't use a third party package for state management unless explicitly asked to do so.**
+- **Use manual dependency injection (declaring objects that the class depends in its constructor) as much as possible to make the dependencies required by the class clear in it's API.**
+- **If asked to use Provider, use it for app-level objects that are used often.**
+- **Use Model-View-ViewModel for application architecture.**
+- **Use ChangeNotifier or a class with ValueNotifiers for ViewModel classes.**
+- **Use a ListenableBuilder to listen to changes to the ViewModel.**
+- **Use a StatefulWidget for widgets that are reusable or single-purpose, and don't necessarily require a MVVM architecture.**
+
+## Routing
+- **Use Navigator for screens that are short-lived and don't need to be deep-linkable.**
+
+## Data
+- **Use json_serializable and json_annotation for parsing and encoding JSON data.**
+- **Use fieldRename: FieldRename.snake to encode data with snake case.**
+
+## Code Generation
+- **Use build_runner for any generated code in the app.**
 
 ## String and Collection Best Practices
 
@@ -409,6 +412,9 @@ Future<User> fetchUser(String id) async {
 
 ## Testing Guidelines
 
+- **Use package:integration_test for integration tests.**
+- **Use package:checks instead of matchers from package:test or package:matcher.**
+
 ### Widget Testing
 ```dart
 testWidgets('CustomButton should call onPressed when tapped', (tester) async {
@@ -477,6 +483,8 @@ group('UserRepository', () {
 
 ## Advanced Dart Patterns
 
+- **Use Patterns and pattern-matching features where possible.**
+
 ### Immutability and Data Classes
 ```dart
 class User {
@@ -680,4 +688,4 @@ class TimeSlot {
 - [ ] Immutable objects used where appropriate
 - [ ] Assert statements used to verify contracts
 
-This unified style guide ensures consistency with both Flutter team practices and official Dart conventions, helping create maintainable, readable code that follows established patterns.
+This unified style guide ensures consistency with both Flutter team practices and official Dart conventions, helping create maintainable, readable code that follows established patterns.