1  # AI Agent Code Block Review Guide
  2  
  3  This guide provides instructions for AI agents to systematically review code blocks in documentation for consistency, accuracy, and best practices.
  4  
  5  ## Overview
  6  
  7  Code blocks in documentation serve as examples, tutorials, and reference implementations. They must be:
  8  - **Accurate**: Work correctly with the current version of Planar
  9  - **Consistent**: Follow established patterns and conventions
 10  - **Complete**: Include necessary imports and setup
 11  - **Educational**: Demonstrate best practices and clear concepts
 12  
 13  ## Review Process
 14  
 15  ### 1. Initial Assessment
 16  
 17  For each documentation file containing code blocks:
 18  
 19  1. **Identify all Julia code blocks** (marked with ```julia)
 20  2. **Categorize by purpose**:
 21     - Tutorial examples (step-by-step learning)
 22     - Reference examples (API demonstration)
 23     - Configuration examples (setup and configuration)
 24     - Advanced examples (complex use cases)
 25  
 26  ### 2. Consistency Checks
 27  
 28  #### Import and Setup Patterns
 29  - **Standard imports**: Verify consistent use of `using Planar` vs `using PlanarInteractive`
 30  - **Project activation**: Check for proper project setup patterns
 31  - **Environment loading**: Ensure `@environment!` macro usage is consistent
 32  
 33  ```julia
 34  # Preferred pattern for basic examples
 35  using Planar
 36  
 37  # Preferred pattern for interactive examples
 38  using PlanarInteractive
 39  @environment!
 40  ```
 41  
 42  #### Naming Conventions
 43  - **Variables**: Use descriptive, consistent names (`strategy`, `exchange`, `config`)
 44  - **Functions**: Follow Julia conventions (snake_case for variables, CamelCase for types)
 45  - **Constants**: Use UPPER_CASE for configuration constants
 46  
 47  #### Code Structure
 48  - **Indentation**: Consistent 4-space indentation
 49  - **Line length**: Respect 92-character limit (JuliaFormatter Blue style)
 50  - **Comments**: Clear, helpful comments that explain non-obvious concepts
 51  
 52  ### 3. Technical Accuracy Review
 53  
 54  #### Version Compatibility
 55  - **API calls**: Verify all function calls match current Planar API
 56  - **Module structure**: Ensure imports reflect current module organization
 57  - **Deprecated features**: Flag any usage of deprecated functions or patterns
 58  
 59  #### Completeness
 60  - **Required imports**: All necessary modules are imported
 61  - **Setup code**: Configuration objects are properly initialized
 62  - **Error handling**: Appropriate error handling for examples that might fail
 63  
 64  #### Planar-Specific Patterns
 65  - **Exchange configuration**: Proper exchange setup with API keys handling
 66  - **Strategy definition**: Consistent strategy structure and inheritance
 67  - **Data handling**: Correct OHLCV data access and manipulation patterns
 68  - **Mode switching**: Proper demonstration of SimMode/PaperMode/LiveMode usage
 69  
 70  ### 4. Educational Value Assessment
 71  
 72  #### Clarity
 73  - **Progressive complexity**: Examples build from simple to complex
 74  - **Explanatory comments**: Code includes helpful explanations
 75  - **Context**: Examples include sufficient context to understand purpose
 76  
 77  #### Best Practices
 78  - **Security**: No hardcoded API keys or sensitive information
 79  - **Performance**: Examples demonstrate efficient patterns
 80  - **Error handling**: Show proper error handling techniques
 81  - **Resource management**: Demonstrate proper cleanup and resource management
 82  
 83  ## Common Issues to Flag
 84  
 85  ### Critical Issues (Must Fix)
 86  - **Syntax errors**: Code that won't parse or run
 87  - **Import errors**: Missing or incorrect module imports
 88  - **API mismatches**: Calls to non-existent or changed functions
 89  - **Security vulnerabilities**: Exposed credentials or unsafe practices
 90  
 91  ### Consistency Issues (Should Fix)
 92  - **Mixed import styles**: Inconsistent use of import patterns
 93  - **Variable naming**: Inconsistent naming conventions
 94  - **Code formatting**: Deviations from JuliaFormatter standards
 95  - **Comment style**: Inconsistent comment formatting
 96  
 97  ### Enhancement Opportunities (Nice to Have)
 98  - **Missing examples**: Gaps in coverage of important features
 99  - **Outdated patterns**: Code using old but still functional approaches
100  - **Performance improvements**: Opportunities to demonstrate better patterns
101  - **Educational improvements**: Ways to make examples clearer
102  
103  ## Review Checklist
104  
105  For each code block, verify:
106  
107  - [ ] **Syntax**: Code parses without errors
108  - [ ] **Imports**: All required modules are imported correctly
109  - [ ] **Compatibility**: Code works with current Planar version
110  - [ ] **Completeness**: Example includes all necessary setup
111  - [ ] **Consistency**: Follows established patterns and conventions
112  - [ ] **Security**: No exposed credentials or unsafe practices
113  - [ ] **Comments**: Adequate explanatory comments
114  - [ ] **Formatting**: Follows JuliaFormatter Blue style
115  - [ ] **Context**: Sufficient context for understanding
116  - [ ] **Best practices**: Demonstrates recommended approaches
117  
118  ## Reporting Format
119  
120  When reporting issues, use this format:
121  
122  ```markdown
123  ## Code Block Review: [File Path]
124  
125  ### Summary
126  - Total code blocks: X
127  - Issues found: Y
128  - Critical issues: Z
129  
130  ### Issues by Category
131  
132  #### Critical Issues
133  - **[File:Line]**: Description of issue
134    - **Problem**: What's wrong
135    - **Impact**: Why it matters
136    - **Suggestion**: How to fix
137  
138  #### Consistency Issues
139  - **[File:Line]**: Description of issue
140    - **Current**: What it currently shows
141    - **Preferred**: What it should show
142    - **Reason**: Why the change improves consistency
143  
144  #### Enhancement Opportunities
145  - **[File:Line]**: Description of opportunity
146    - **Current**: Current approach
147    - **Enhancement**: Suggested improvement
148    - **Benefit**: Why the improvement helps users
149  ```
150  
151  ## Integration with Planar Ecosystem
152  
153  ### Module Awareness
154  - **Core modules**: Engine, Strategies, Exchanges, Executors
155  - **Data modules**: Data, Fetch, Processing, Metrics
156  - **Utility modules**: Collections, Misc, Lang, TimeTicks
157  - **Interactive modules**: Plotting, Opt, PlanarInteractive
158  
159  ### Configuration Patterns
160  - **User directory**: Examples should reference `user/` directory structure
161  - **Configuration files**: Proper use of `planar.toml` and `secrets.toml`
162  - **Strategy organization**: Both file-based and package-based approaches
163  
164  ### Common Planar Patterns
165  - **Strategy lifecycle**: Initialization, execution, cleanup
166  - **Data pipeline**: Fetching, processing, storage, retrieval
167  - **Exchange interaction**: Authentication, API calls, error handling
168  - **Mode transitions**: Moving between simulation, paper, and live trading
169  
170  ## Automation Considerations
171  
172  While this guide is designed for AI agents, consider these automation opportunities:
173  
174  - **Syntax checking**: Automated parsing and compilation checks
175  - **Import validation**: Verify all imports resolve correctly
176  - **Pattern matching**: Automated detection of common anti-patterns
177  - **Consistency scoring**: Metrics for measuring consistency across examples
178  
179  ## Maintenance
180  
181  This guide should be updated when:
182  - Planar API changes significantly
183  - New modules or patterns are introduced
184  - Documentation standards evolve
185  - Common issues patterns emerge from reviews
186  
187  ---
188  
189  *This guide is part of the Planar documentation maintenance system. For questions or improvements, see the main documentation contribution guidelines.*