From 468ad3333d257faa0aee291687aed511d8c6e8e7 Mon Sep 17 00:00:00 2001 From: Eric Windmill Date: Thu, 7 Aug 2025 15:54:45 -0400 Subject: [PATCH] update llm instructions --- .prompts/code_freshness.md | 104 ++++++++++++++++++++----------------- 1 file changed, 56 insertions(+), 48 deletions(-) diff --git a/.prompts/code_freshness.md b/.prompts/code_freshness.md index dce8bc169..6b28e9a5e 100644 --- a/.prompts/code_freshness.md +++ b/.prompts/code_freshness.md @@ -1,55 +1,63 @@ -# Code Health and Style Guide Adherence Log +# Code Health and Style Guide Analysis -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 document provides instructions for an AI assistant to analyze this repository against the Dart and Flutter style guide (`.prompts/llm.md`) and log opportunities for improvement. ## Workflow -The AI assistant performs the following steps for **each sample project** in the repository: +The AI assistant must follow these steps exactly: -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/`:** +### 1. Setup + +1. **Create Log Directory**: If it does not already exist, create a directory named `logs` in the repository root. +2. **Create Log File**: Create a new file inside the `logs` directory named `YYYY-MM-DD_HH-MM-SS-freshness-scores.md`, where `YYYY-MM-DD_HH-MM-SS` is the current timestamp. + +### 2. Project Identification + +1. **Find Projects**: Identify all sample projects by searching for `pubspec.yaml` files within the repository. Each directory containing a `pubspec.yaml` should be considered a separate project. +2. **Create a Queue**: Compile a list of the absolute paths to these project directories to process them one by one. + +### 3. Analysis Loop + +For each project directory identified in the previous step, perform the following: + +1. **Check for Dart Files**: + * Verify that the project directory contains at least one `.dart` file. + * If not, add an entry to the log file stating that the project was skipped for this reason and proceed to the next project. + +2. **Analyze Git History**: + * Run `git log` to find the most recent commit to a `.dart` file within that project's directory made by a human (i.e., not a bot). + * **Command**: ```bash - git log -1 --author='^(?!.*bot).*$' --pretty="format:%ad" --date=short -- ./sample_name/**/*.dart + git log -1 --author='^(?!.*bot).*$' --pretty="format:%ad" --date=short -- ./**/*.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` - -* **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. \ No newline at end of file + *(Note: This command should be run from within the project's directory).* + * **Handle No Commits**: If the command returns no output, note "No human commits found" for the log. If there are no commits at all, note that as well. + +3. **Read and Assess Code**: + * Read all `.dart` files within the project directory (recursively). + * Compare the code against the rules and patterns defined in `.prompts/llm.md`. + * The assessment must focus on: + * Code organization and structure. + * Adherence to naming conventions. + * Proper use of Flutter and Dart patterns (e.g., `const` constructors, collection literals). + * State management best practices. + * Clarity, readability, and documentation. + +4. **Log Findings**: + * Append a new entry to the log file using the following Markdown template. Ensure all fields are filled out. + + ```markdown + --- + **Sample**: `path/to/sample` + **Last Human Commit**: `YYYY-MM-DD` or "No human commits found" + **Assessment Date**: `YYYY-MM-DD` + + **Summary of Style Guide Adherence**: + A brief, one-paragraph summary of how well the project adheres to the style guide. Mention its strengths and weaknesses in general terms. + + **Opportunities for Improvement**: + - A concrete, actionable bullet point describing a specific area for improvement. + - Another actionable bullet point. + - A third bullet point, if applicable. Focus on providing clear, specific, and helpful recommendations. + --- + ``` \ No newline at end of file