# Technical Quality Evaluator

## Purpose

This evaluator assesses the technical excellence of iterations across four dimensions: code quality, architecture, performance, and robustness. It uses ReAct reasoning to make fair, evidence-based assessments.

## Evaluation Process

### THOUGHT Phase: Pre-Evaluation Reasoning

Before scoring, reason about:

1. **What technical excellence means for this type of output**
   - What are the technical challenges?
   - What would "great" look like?
   - What are common technical pitfalls?

2. **What evidence to look for**
   - Code patterns indicating quality
   - Architectural decisions
   - Performance characteristics
   - Error handling approaches

3. **How to remain objective**
   - Focus on measurable qualities
   - Compare against standards, not other iterations
   - Avoid personal preferences
   - Look for concrete evidence

### ACTION Phase: Technical Assessment

#### 1. Code Quality Assessment (0-25 points)

**Read the entire codebase and evaluate:**

**Readability (0-7 points)**
- Is code easy to understand at a glance?
- Is formatting consistent?
- Are complex sections broken into digestible chunks?
- Is indentation and spacing appropriate?

Evidence to look for:
- Consistent indentation (2 or 4 spaces)
- Logical grouping of related code
- Blank lines separating sections
- No overly long lines (> 120 chars)

**Comments & Documentation (0-6 points)**
- Are complex sections explained?
- Are function purposes documented?
- Are edge cases noted?
- Are algorithms explained?

Evidence to look for:
```javascript
// Good: Explains why and what
// Use binary search for O(log n) performance on sorted data
function binarySearch(arr, target) { ... }

// Bad: States obvious
// This function searches
function search(arr, target) { ... }
```

**Naming Conventions (0-6 points)**
- Are names descriptive and self-documenting?
- Do names follow conventions (camelCase for JS, etc.)?
- Are names appropriately scoped?
- Are magic numbers avoided?

Evidence to look for:
```javascript
// Good
const MAX_RETRY_ATTEMPTS = 3;
function calculateAverageTemperature(readings) { ... }

// Bad
const x = 3;
function calc(r) { ... }
```

**DRY Principle (0-6 points)**
- Is code duplication avoided?
- Are repeated patterns extracted into functions?
- Are constants defined once?
- Are utilities reused?

Evidence to look for:
- No copy-pasted code blocks
- Shared functions for common operations
- Constants defined at top
- Helper functions for repeated logic

**Score Code Quality**: Sum of above (0-25)

#### 2. Architecture Assessment (0-25 points)

**Analyze the overall structure:**

**Modularity (0-7 points)**
- Is code broken into logical modules/functions?
- Are modules self-contained?
- Are functions single-purpose?
- Is there clear module organization?

Evidence to look for:
```javascript
// Good: Modular structure
class DataProcessor {
  load() { ... }
  transform() { ... }
  validate() { ... }
}

class Renderer {
  setup() { ... }
  draw() { ... }
  update() { ... }
}

// Bad: Monolithic
function doEverything() {
  // 500 lines of mixed concerns
}
```

**Separation of Concerns (0-6 points)**
- Are data, presentation, and logic separated?
- Is business logic separate from UI?
- Are concerns clearly delineated?

Evidence to look for:
- Data management separate from rendering
- Event handlers separate from business logic
- Configuration separate from implementation

**Reusability (0-6 points)**
- Can components be reused?
- Are functions generic where appropriate?
- Are utilities extracted?
- Is coupling minimized?

Evidence to look for:
- Generic utility functions
- Configurable components
- Minimal dependencies between modules
- Clear interfaces

**Scalability (0-6 points)**
- Would this architecture scale to larger problems?
- Are patterns in place for growth?
- Is performance maintained with scale?
- Are extensibility points clear?

Evidence to look for:
- Efficient data structures
- Algorithmic complexity consideration
- Extensible design patterns
- Clear growth paths

**Score Architecture**: Sum of above (0-25)

#### 3. Performance Assessment (0-25 points)

**Evaluate performance characteristics:**

**Initial Render Speed (0-7 points)**
- How quickly does it load and render?
- Are blocking operations minimized?
- Is critical path optimized?

Scoring guide:
- 7 points: < 200ms render
- 5-6 points: 200-400ms render
- 3-4 points: 400-700ms render
- 1-2 points: 700-1000ms render
- 0 points: > 1000ms render

Evidence to look for:
- Async loading where appropriate
- Minimal render-blocking code
- Efficient initial setup

**Animation Performance (0-6 points)**
- Are animations smooth (60fps)?
- Is requestAnimationFrame used?
- Are animations optimized?

Scoring guide:
- 6 points: Consistently 60fps
- 4-5 points: Mostly 60fps, occasional drops
- 2-3 points: 30-50fps, noticeable jank
- 0-1 points: < 30fps, very janky

Evidence to look for:
```javascript
// Good: requestAnimationFrame
function animate() {
  requestAnimationFrame(animate);
  update();
  render();
}

// Bad: setInterval
setInterval(() => {
  update();
  render();
}, 16);
```

**Algorithm Efficiency (0-6 points)**
- Are algorithms efficient?
- Is time complexity appropriate?
- Are data structures well-chosen?

Evidence to look for:
- O(n log n) or better for sorting
- O(log n) for searching sorted data
- O(1) for lookups (using Maps/Objects)
- Avoids O(n²) where possible

**DOM Optimization (0-6 points)**
- Are DOM operations batched?
- Are unnecessary reflows avoided?
- Is virtual DOM or similar used if appropriate?

Evidence to look for:
```javascript
// Good: Batch DOM updates
const fragment = document.createDocumentFragment();
items.forEach(item => {
  fragment.appendChild(createNode(item));
});
container.appendChild(fragment);

// Bad: Repeated DOM updates
items.forEach(item => {
  container.appendChild(createNode(item));
});
```

**Score Performance**: Sum of above (0-25)

#### 4. Robustness Assessment (0-25 points)

**Evaluate error handling and edge cases:**

**Input Validation (0-7 points)**
- Is input validated before use?
- Are assumptions checked?
- Are invalid inputs rejected gracefully?

Evidence to look for:
```javascript
// Good: Validation
function processData(data) {
  if (!Array.isArray(data)) {
    throw new Error('Data must be array');
  }
  if (data.length === 0) {
    console.warn('Empty data provided');
    return [];
  }
  // ... process
}

// Bad: No validation
function processData(data) {
  return data.map(d => d.value); // Crashes if data is null
}
```

**Error Handling (0-6 points)**
- Are errors caught and handled?
- Is error feedback provided to users?
- Are errors logged appropriately?

Evidence to look for:
- try/catch blocks around risky operations
- User-friendly error messages
- Graceful degradation on errors

**Edge Case Coverage (0-6 points)**
- What about empty data?
- What about huge data?
- What about invalid data?
- What about extreme values?

Evidence to look for:
- Tests or handling for empty arrays
- Performance with large datasets
- Handling of null/undefined
- Boundary value handling

**Cross-Browser Compatibility (0-6 points)**
- Does it use standard APIs?
- Are polyfills provided if needed?
- Is fallback behavior defined?

Evidence to look for:
- Standard DOM APIs
- Modern JavaScript features with fallbacks
- CSS vendor prefixes if needed
- Feature detection

**Score Robustness**: Sum of above (0-25)

### OBSERVATION Phase: Results Analysis

**Calculate Total Technical Score**:
```
technical_score = code_quality + architecture + performance + robustness
```

Range: 0-100

**Analyze Results**:

1. **What are the technical strengths?**
   - Which dimensions scored highest?
   - What specific evidence supports strength?
   - What patterns can be learned from?

2. **What are the technical weaknesses?**
   - Which dimensions scored lowest?
   - What specific issues were found?
   - What improvements would help most?

3. **Are there trade-offs evident?**
   - Performance vs robustness?
   - Simplicity vs architecture?
   - Speed vs quality?

4. **What does this score mean?**
   - Is this score fair given the evidence?
   - Does it reflect actual technical quality?
   - What would improve this score by 10 points?

## Output Format

```json
{
  "dimension": "technical",
  "total_score": 78,
  "breakdown": {
    "code_quality": 20,
    "architecture": 19,
    "performance": 18,
    "robustness": 21
  },
  "strengths": [
    "Excellent input validation and error handling",
    "Clean, well-commented code structure",
    "Efficient use of data structures"
  ],
  "weaknesses": [
    "Some code duplication in rendering functions",
    "Performance could be optimized for large datasets",
    "Animation frame rate drops with complex interactions"
  ],
  "evidence": {
    "code_quality": {
      "readability": 6,
      "comments": 5,
      "naming": 5,
      "dry_principle": 4,
      "examples": [
        "Line 45-67: Excellent validation with clear error messages",
        "Line 120-135: Some repeated DOM manipulation code"
      ]
    },
    "architecture": {
      "modularity": 6,
      "separation": 5,
      "reusability": 4,
      "scalability": 4,
      "examples": [
        "Clear separation between DataProcessor and Renderer classes",
        "Some tight coupling between visualization and controls"
      ]
    },
    "performance": {
      "render_speed": 5,
      "animation": 4,
      "algorithms": 5,
      "dom_optimization": 4,
      "examples": [
        "Initial render: ~350ms (good)",
        "Animation: 55fps average (acceptable with occasional drops)"
      ]
    },
    "robustness": {
      "validation": 6,
      "error_handling": 5,
      "edge_cases": 5,
      "compatibility": 5,
      "examples": [
        "Comprehensive input validation on lines 23-45",
        "Handles empty data gracefully with user feedback"
      ]
    }
  },
  "reasoning": "This iteration demonstrates strong technical fundamentals with particularly excellent robustness through comprehensive validation and error handling. Code quality is high with good comments and naming, though some DRY violations exist in rendering code. Architecture is solid with clear class separation, though some coupling could be reduced. Performance is acceptable but could benefit from optimization for larger datasets and more consistent frame rates. Overall, this represents above-average technical quality with clear paths for improvement.",
  "improvement_suggestions": [
    "Extract repeated rendering code into reusable utility functions",
    "Optimize data processing for datasets > 1000 points",
    "Use requestAnimationFrame consistently for all animations",
    "Reduce coupling between visualization and control components"
  ]
}
```

## Calibration Examples

**Score 90-100 (Exceptional)**:
- Clean, elegant code throughout
- Highly modular, extensible architecture
- Fast render (< 200ms), smooth 60fps animations
- Comprehensive validation, error handling, edge cases
- Example: Production-quality code with professional polish

**Score 80-89 (Excellent)**:
- Well-written, readable code
- Good modular structure
- Good performance (< 400ms, mostly 60fps)
- Solid validation and error handling
- Example: Strong technical implementation

**Score 70-79 (Good)**:
- Decent code quality with minor issues
- Reasonable architecture
- Acceptable performance (< 700ms, > 45fps)
- Basic validation and error handling
- Example: Solid work, room for improvement

**Score 60-69 (Adequate)**:
- Functional code with quality issues
- Basic structure, some organization
- Adequate performance (< 1s, > 30fps)
- Minimal validation and error handling
- Example: Gets job done, needs refinement

**Score Below 60 (Needs Improvement)**:
- Code quality issues throughout
- Poor or no architecture
- Performance problems
- Little to no validation or error handling
- Example: Significant technical deficiencies

## ReAct Reminder

Every technical evaluation should:
1. **THOUGHT**: Reason about technical excellence for this context
2. **ACTION**: Systematically assess each dimension
3. **OBSERVATION**: Analyze what the scores reveal

Document reasoning to ensure transparent, fair assessment.

---

**Remember**: Technical quality is objective and measurable. Focus on evidence, apply criteria consistently, and let the code speak for itself.
