/eval-code-quality

name: eval-code-quality
description: "Specialized code quality evaluator for the Evaluate-Loop. Use this for evaluating code implementation tracks where the deliverable is functional code — features, API routes, state management, utilities. Checks build integrity, type safety, code patterns, error handling, dead code, imports, test coverage, and naming conventions. Dispatched by loop-execution-evaluator when track type is 'feature', 'refactor', or 'infrastructure'. Triggered by: 'evaluate code', 'code review', 'quality check', 'build check'."

Code Quality Evaluator Agent

Specialized evaluator for tracks whose deliverables are functional code — features, state management, utilities, API routes.

When This Evaluator Is Used

Dispatched by `loop-execution-evaluator` when the track is one of:

• Feature implementation (e.g., user authentication, data processing)
• Infrastructure/utility work
• Refactoring tracks
• State management (Zustand, hooks)

Inputs Required

1. Track's `spec.md` and `plan.md` 2. Changed files (from plan.md task summaries or git diff) 3. `tsconfig.json` — TypeScript config 4. `package.json` — dependencies and scripts 5. Existing test files (if any)

Evaluation Passes (6 checks)

Pass 1: Build Integrity

npm run build    # Must exit 0
npx tsc --noEmit # Must exit 0 (no type errors)

### Build: PASS ✅ / FAIL ❌
- Build status: [success / X errors]
- Type check: [clean / X type errors]
- Errors: [list if any]

Pass 2: Type Safety

| Check | What to Look For | |-------|-----------------| | No `any` types | Explicit typing on all exports, function params, return types | | Generic usage | API responses typed with `ApiResponse<T>` | | Null safety | Optional chaining (`?.`) or null checks where data may be absent | | Type exports | Shared types in `src/types/`, not inline | | Interface consistency | Types match spec/product.md schema |

### Type Safety: PASS ✅ / FAIL ❌
- `any` usage: [count] — [list files:lines]
- Missing types: [list untyped exports]
- Null safety issues: [list]

Pass 3: Code Patterns & State Management

| Check | What to Look For | |-------|-----------------| | File structure | Files in correct directories per component architecture | | Naming | kebab-case files, PascalCase components, `{Component}Props` | | Imports | No circular imports, no unused imports | | DRY | No significant code duplication (>10 lines repeated) | | Single responsibility | Functions/components do one thing | | Module boundaries | Feature code in feature dirs, shared code in `ui/` or `lib/` | | **State sync** | **Every client state mutation has corresponding API endpoint** | | **Optimistic updates** | **Rollback logic present on API failure** | | **Source of truth** | **Server (DB) is source of truth, client is cache** |

**State Sync Anti-Patterns to Flag:**

// ❌ BAD: State updated without API persistence
const toggleLock = (id) => {
  set({ assets: { ...assets, [id]: { locked: true } } });
  // No API call!
}

// ✅ GOOD: Optimistic update with API sync
const toggleLock = async (id) => {
  const prev = assets;
  set({ assets: { ...assets, [id]: { locked: true } } }); // Optimistic
  try {
    await fetch(`/api/assets/${id}`, {
      method: 'PATCH',
      body: JSON.stringify({ locked: true })
    });
  } catch (err) {
    set({ assets: prev }); // Rollback
    throw err;
  }
}

### Code Patterns & State Sync: PASS ✅ / FAIL ❌
- Naming violations: [list]
- Unused imports: [list files]
- Duplication found: [describe]
- **State mutations without API: [count] — [list]**
- **Missing rollback logic: [count] — [list]**
- **API endpoints without client updates: [count] — [list]**

Pass 4: Error Handling

| Check | What to Look For | |-------|-----------------| | API calls | try/catch or error handling on all async operations | | User feedback | Toast/inline error shown to user on failure | | Null data | Empty states handled (no data, loading, error) | | Edge cases | Invalid input, network failure, timeout | | No silent failures | Errors not swallowed without user notification |

### Error Handling: PASS ✅ / FAIL ❌
- Unhandled async: [list functions]
- Missing user feedback: [list scenarios]
- Silent failures: [list]

Pass 5: Dead Code & Cleanup

| Check | What to Look For | |-------|-----------------| | Unused exports | Functions/components exported but never imported | | Commented code | Large blocks of commented-out code (should be deleted) | | Unused files | Files that exist but aren't imported anywhere | | TODO/FIXME | Unresolved TODO comments | | Console logs | `console.log` left in production code |

### Dead Code: PASS ✅ / FAIL ❌
- Unused exports: [list]
- Console logs: [list files:lines]
- TODOs: [list]

Pass 6: Test Coverage (when applicable)

| Check | Target | |-------|--------| | Overall coverage | 70% | | Business logic | 90% | | API routes | 80% | | Utility functions | 80% |

### Tests: PASS ✅ / FAIL ❌ / ⚠️ NOT CONFIGURED
- Coverage: [X]% overall
- Business logic: [X]%
- Untested critical paths: [list]

Verdict Template

## Code Quality Evaluation Report

**Track**: [track-id]
**Evaluator**: eval-code-quality
**Date**: [YYYY-MM-DD]
**Files Evaluated**: [count]

### Results
| Pass | Status | Issues |
|------|--------|--------|
| 1. Build | PASS/FAIL | [details] |
| 2. Type Safety | PASS/FAIL | [count] issues |
| 3. Code Patterns | PASS/FAIL | [count] issues |
| 4. Error Handling | PASS/FAIL | [count] issues |
| 5. Dead Code | PASS/FAIL | [count] issues |
| 6. Tests | PASS/FAIL/N/A | [coverage] |

### Verdict: PASS ✅ / FAIL ❌
[If FAIL, list specific fix actions for loop-fixer]

Handoff

• **PASS** → Return to `loop-execution-evaluator` → Conductor marks complete
• **FAIL** → Return to `loop-execution-evaluator` → Conductor dispatches `loop-fixer`