Enhance Augment Code Review guidelines with real-world insights

[phodal]

Overview

This PR enhances the Augment Code Review guidelines added in #41 with insights from real-world code review examples.

Motivation

After reviewing excellent Augment Code Review comments from the Chapi project (#37 and #38), I identified several important patterns that should be codified in our review guidelines.

Changes Summary

New Rules Added (6 total)

Code Analysis Accuracy

1. scope_tracking_correctness (High severity)

   • Prevents misattribution in nested scopes
   • Inspired by: chapi#37 review comment
   • Example issue: Shared classFields list causing outer class fields to be assigned to inner classes

2. complete_syntax_coverage (High severity)

   • Ensures all syntax variants are handled in parsers
   • Inspired by: chapi#38 review comment
   • Example issue: Generator expressions being truncated when only capturing test(0).text

Testing

3. edge_case_coverage (High severity)

   • Comprehensive testing of corner scenarios
   • Especially important for parsers: nested structures, special operators, syntax variants

4. test_completeness (Medium severity)

   • Verify complete behavior, not just happy path
   • Check that all expected data is captured and nothing is dropped or misattributed

Code Quality

5. data_structure_choice (Medium severity)

   • Use appropriate data structures for the problem
   • Example: Use stacks for nested scopes instead of shared lists

6. state_management (High severity)

   • Proper scoping of mutable state in hierarchical structures
   • Ensure state is cleared at the right boundaries

Enhanced Existing Rules (2 total)

1. ast_parsing_correctness

   • Added: "Consider all grammar alternatives (e.g., generator expressions, comprehensions)"

2. analysis_result_validation

   • Added: "Ensure no data is dropped or truncated during parsing"

Real-World Examples

Example 1: Nested Scope Tracking Issue

From: chapi#37

"Using a single shared classFields list here will misattribute fields when classes are nested: fields collected in the outer class before entering an inner class will be assigned to the inner class and then cleared, causing them to be missing from the outer class upon its exit."

Problem: Shared mutable state across nested scopes

Solution: Use stack-based tracking or per-instance collections

Rules Added: scope_tracking_correctness, state_management, data_structure_choice

Example 2: Incomplete Syntax Handling

From: chapi#38

"For arguments of the form test comp_for (e.g., generator expressions f(x for x in a)), using only test(0).text will drop the comprehension and record just x; consider handling the comp_for case so the full argument is captured."

Problem: Parser only handling common cases, missing edge cases

Solution: Handle all grammar alternatives in the parser

Rules Added: complete_syntax_coverage, edge_case_coverage, test_completeness

Impact

Before

• 21 rules across 9 areas
• General best practices

After

• 27 rules across 9 areas (+6 new rules)
• Battle-tested insights from real code reviews
• Specific guidance for common pitfalls in code analysis tools

Severity Distribution

• High: 11 rules (critical issues that can cause bugs)
• Medium: 13 rules (important quality issues)
• Low: 3 rules (nice-to-have improvements)

Benefits

1. Proactive Issue Detection: Augment will catch issues similar to those found in Chapi
2. Knowledge Transfer: Codifies expert review insights into automated checks
3. Consistency: Ensures these patterns are checked in every PR
4. Educational: Developers learn from real examples
5. Project-Specific: Tailored for code analysis tools like Coca

Testing

The enhanced YAML file:

• ✅ Validates against Augment's schema
• ✅ Follows the documented format
• ✅ Contains clear, actionable descriptions
• ✅ Uses appropriate severity levels

Files Changed

• .augment/code_review_guidelines.yaml (+33 lines, -9 lines)

References

• Augment Code Review Admin Guide
• chapi#37 - Nested scope tracking issue
• chapi#38 - Complete syntax coverage issue
• Previous PR #41 - Initial guidelines

---

Diff Preview

Key additions include:

code_analysis_accuracy:
  rules:
    # NEW: Prevents nested scope misattribution
    - id: "scope_tracking_correctness"
      description: "When tracking variable or symbol scope, use proper data structures..."
      severity: "high"
    
    # NEW: Ensures complete syntax handling
    - id: "complete_syntax_coverage"
      description: "When parsing language constructs, ensure all syntax variants are handled..."
      severity: "high"

testing:
  rules:
    # NEW: Comprehensive edge case testing
    - id: "edge_case_coverage"
      description: "When adding new features or fixing bugs, ensure tests cover edge cases..."
      severity: "high"
    
    # NEW: Complete behavior verification
    - id: "test_completeness"
      description: "Tests should verify the complete behavior, not just the happy path..."
      severity: "medium"

code_quality:
  rules:
    # NEW: Appropriate data structure selection
    - id: "data_structure_choice"
      description: "Choose appropriate data structures for the problem..."
      severity: "medium"
    
    # NEW: Proper state scoping
    - id: "state_management"
      description: "Be careful with shared mutable state..."
      severity: "high"

---

Pull Request opened by Augment Code with guidance from the PR author

Summary by CodeRabbit

• Documentation
  • Strengthened code review guidelines to enhance overall code quality and system reliability
  • Added new validation standards to ensure comprehensive parsing and complete syntax coverage
  • Introduced enhanced testing requirements for edge cases, nested structures, and syntax variants
  • Updated best practices for appropriate data structure design and proper state management

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Caution

Review failed

The pull request is closed.

Walkthrough

Updated code review guidelines in a configuration file to emphasize AST parsing correctness, scope tracking integrity, syntax coverage completeness, and rigorous edge-case testing for parser implementations.

Changes

Cohort / File(s)	Summary
Code Review Guidelines \.augment/code_review_guidelines\.yaml	Enhanced AST parsing rule description; expanded analysis validation; added high-severity rules for scope tracking correctness, complete syntax coverage, edge-case coverage, and test completeness; added code quality guidance on data structure choice and state management.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

• Review new rule descriptions for clarity and technical accuracy
• Verify new severity classifications align with guidelines framework
• Confirm guidance on scope tracking, data structures, and state management is applicable and precise

Poem

🐰 A parser's heart must beat so true,
With scopes aligned and syntax through,
No data lost in nested rings,
And edge cases caught by testing wings,
Guidelines carved, our craft takes flight!

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch enhance-code-review-guidelines

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 63228b5 and 6245801.

📒 Files selected for processing (1)

• .augment/code_review_guidelines.yaml (3 hunks)

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[augmentcode]

Review completed. No suggestions at this time.

Comment augment review to trigger a new review at any time.