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
- Track's
spec.md and plan.md
- Changed files (from plan.md task summaries or git diff)
tsconfig.json — TypeScript configpackage.json — dependencies and scripts- 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
