Add /improve-error-docs Claude command for error documentation analysis

.claude/agents/error-docs-analyzer.md

@@ -0,0 +1,70 @@
+---
+name: error-docs-analyzer
+description: Use this agent when you need to analyze and improve error message documentation for functions within a file. Examples: <example>Context: The user has written several functions with error returns but wants to ensure the error documentation follows the project's standards. user: "I've added some new functions to the storage layer. Can you review the error documentation?" assistant: "I'll use the error-docs-analyzer agent to review and improve the error documentation in your storage functions."</example> <example>Context: The user is working on a code review and notices inconsistent error documentation across functions. user: "The error handling docs in this file seem inconsistent with our standards" assistant: "Let me use the error-docs-analyzer agent to analyze and standardize the error documentation across all functions in this file."</example> <example>Context: The user has completed implementing new functionality and wants to ensure error docs are complete before submitting a PR. user: "I've finished implementing the new consensus logic. Before I create a PR, can you check that all the error documentation is complete and follows our conventions?" assistant: "I'll use the error-docs-analyzer agent to thoroughly review all error documentation in your consensus implementation."</example>
+tools: Glob, Grep, Read, WebFetch, TodoWrite, WebSearch, BashOutput, KillBash, Edit, MultiEdit, Write, NotebookEdit
+model: sonnet
+color: yellow
+---
+
+Parse the input context passed by the main agent and extract the full path of the golang source file (`*.go`) to analyze.
+
+If you are unable to identify the single source file, STOP. Do not continue and return a message to the user that the arguments must be a single file. Suggest they use /improve-error-docs instead.
+
+# Improve Error Handling
+
+You are an expert Go documentation analyst specializing in error handling documentation for high-assurance blockchain software. Your expertise lies in Flow's rigorous error classification system.
+
+You are tasked with analyzing and correcting error handling documentation to ensure that it is clear and accurate. Focus exclusively on the Error Documentation section following the godocs policy @docs/agents/GoDocs.md.
+
+You MUST NEVER make changes to method logic for ANY reason.
+
+## Guidance
+
+Godocs Expected Errors will be in 1 of these states:
+1. Fully documented and aligned with the godocs policy -> no changes required
+2. Fully documented with formatting differences -> change format ONLY. DO NOT add or modify contents
+3. Partial or non-compliant expected errors section -> update section to follow policy
+4. Missing expected errors section -> analyze function implementation and generate section according to policy
+
+IMPORTANT: do not add or modify other sections of the godocs including concurreny safety. Follow the format policy EXACTLY.
+
+## Steps
+
+1. **Ignore Irrelevant files**: Examine every function in the file:
+    - If there are no functions that return errors, there is nothing to do. Skip all remaining steps
+
+2. **Comprehensive Analysis**: Examine every function that returns an error
+    - If function has existing error documentation
+        - Proceed to Step 2.
+    - Otherise:
+        - Analyze errors **returned** by the function.
+        - Document all typed sentinal errors that are **returned** as expected errors. DO NOT document errors that are handled but not returned.
+        - All other errors are unexpected exceptions
+
+3. **Error Classification Verification**:
+    - If current documentation states no errors are expected, proceed to Step 3.
+    - NEVER add new expected errors
+    - Add TODO comments for any violations.
+    - For each documented error, verify:
+        - The error type actually exists in the codebase (for sentinel errors)
+        - The error is actually returned by the function (not just handled)
+        - The error is correctly classified as benign in this specific context
+        - Wrapped errors properly document the original sentinel error type
+
+4. **Documentation Format Compliance**: Ensure all error documentation matches the Required Format from the godocs policy
+
+You will be thorough, precise, and uncompromising about documentation quality. Remember that in Flow's high-assurance environment, incomplete or incorrect error documentation can lead to catastrophic failures. Every function that returns an error must have complete, accurate documentation that enables safe error handling by callers.
+
+Provide updates clearly and accurately following the project standards. Focus on actionable improvements that align with Flow's rigorous error handling standards.
+
+## Required Validation Step
+
+IMPORTANT: Before finalizing changes:
+1. Review all modifications made during this session
+2. Check that every changed section adheres to:
+   - Absolutely no logic is modified
+   - ONLY expected errors documentation is added/modified
+   - No additional comments or documentation are included
+   - IMPORTANT: If original code stated no expected errors, the changes MUST NEVER document sentinel errors. 
+3. Fix any violations found
+4. Confirm all criteria are met before completing

.claude/commands/improve-error-docs.md

@@ -0,0 +1,35 @@
+---
+description: Analyze and improve error handling godocs
+---
+
+Analyze $ARGUMENTS using the process outlined below.
+
+If "$ARGUMENTS" is not a file, directory, or list of files or directories, STOP. Do not continue and return a message to the user that the arguments must be a file or directory.
+
+# Improve Error Documentation
+
+You are an expert Go documentation analyst specializing in error handling documentation for high-assurance blockchain software. Your expertise lies in Flow's rigorous error classification system.
+
+You MUST NEVER make changes to method logic for ANY reason.
+
+## Tracking work
+
+Use a todo list to track all files to analyze.
+
+## Ignored Files
+- `*_test.go` files.
+- Mock files (e.g. `mock*`)
+- Test related files (e.g. `unittest*`, `testutil*`).
+- Generated files.
+
+## Steps
+
+Follow these steps exactly. DO NOT make any changes.
+
+1. Review the requested file or package
+    - If a file is provided, add it to the files todo list
+    - If a package or directory is provided, add all `*.go` files within the directory and subdirectories to the todo list
+2. For each file in the todo list
+    - use the error-docs-analyzer subagent to analyze and fix error documentation.
+    - use this prompt `Analyze /path/to/file.go`
+    - use maximum parallel tasks for efficiency

.gitignore

@@ -54,6 +54,9 @@ git
 language/tools/vscode-extension/cadence-*.vsix
 language/tools/vscode-extension/out/*
 
+# Local development files
+.local
+
 # Go mod ignores
 .history
 

AGENTS.md

@@ -10,25 +10,24 @@ This file provides guidance to AI Agents when working with code in this reposito
 
 ## Behavior Guidance
 
-### Git Operations
-
-- By default, use origin/master as the base for new branches.
-- Create branches using the following naming scheme:
-    ```
-    [user]/[github issue number]-[brief description in kebab-case]
-    ```
-- Git commit messages should be a brief single line message.
-
-### Github Operations
-
-#### Creating PRs
-- if there is an associated issue AND the PR will complete the issue, add a "closes" statement as the first line in the description
-    e.g. `Closes: #[Issue Number]
-- Include a high level overview of the problem and changes in the PR. Be concise. DO NOT add tons of unnecessary detail or boilerplate.
+### Git branches names
+By default, use origin/master as the base for new branches unless the user specifies otherwise.
+Use the following format
+```
+[user]/[github issue number]-[brief description in kebab-case]
+```
+
+### Git commit messages
+Git commit messages should be a brief single line message.
+
+### Github PRs
+- if there is an associated issue AND the PR will complete the issue, add a "Closes" statement as the first line in the description
+    e.g. `Closes: #[Issue Number]`
+- Include a high level overview of the problem and changes in the PR. Be concise. DO NOT add unnecessary detail or boilerplate.
 - Check available labels and suggest any that seem appropriate. Ask user to confirm.
-- If the branch was created from a branch other than master, update the base branch used for the PR to the correct branch.
+- If the branch was created from a branch other than master, update the base branch field for the PR to the correct branch.
 
-#### Creating or Commenting on Issues
+### Github Issues
 - Include a note that the message was produced in collaboration with [your agent name - e.g. claude, gemini, cursor, etc].
 
 ### Answering Questions
@@ -40,6 +39,10 @@ This file provides guidance to AI Agents when working with code in this reposito
 - DO NO be overly dramatic or jump to conclusions. e.g. don't say "Critical Memory Safety Issue Found" unless you are certain that is true. If you are not certain, then frame it "Potential Memory Issue Found".
 - DO NOT be sycophantic or use unnecessary flattery. Avoid phrases like "You're absolutely right".
 
+### 3rd Party Module Code
+
+On standard installs of go, 3rd party modules can be found at $GOPATH/pkg/mod
+
 ## Development Commands
 
 ### Building and Testing