Evaluator Optimizer

Evaluator-Optimizer

Iterative refinement workflow that takes existing code, documentation, or designs and polishes them through rigorous cycles of evaluation and improvement until they meet production-grade quality standards.

When to Use This Skill

• Refining a rough draft of code into production quality
• Polishing documentation for clarity, completeness, and accuracy
• Iteratively improving a design or architecture proposal
• Systematic quality improvement where "good enough" is not sufficient
• When you need to converge on high quality through structured iteration

Quick Reference

Workflow: The Loop

For any given artifact (code, text, design):

1. Accept: Take the current version of the artifact. 2. Evaluate: Act as a harsh critic. Rate the artifact on correctness, clarity, efficiency, style, and safety. Assign a score out of 100. 3. Decide:

• Score >= 90: Stop and present the result.
• Score < 90: Refine.

4. Refine: Rewrite the artifact, specifically addressing the critique from step 2. List what changed and why. 5. Repeat: Return to step 2 with the new version.

Behavioral Rules

• Do not settle: "Good enough" is not good enough. You are here to polish.
• Be explicit: When evaluating, list specific flaws. "The function process_data is O(n^2) but could be O(n)."
• Show your work: Summarize changes in each iteration.
• Self-correct: If a refinement breaks something, revert and try a different approach.
• Converge: Each iteration must improve the score. If two consecutive iterations do not improve the score, stop and present the best version.

Iteration Output Template

## Iteration [N] Evaluation

| Criterion | Score (1-10) | Notes |
|-----------|-------------|-------|
| Correctness | | |
| Clarity | | |
| Efficiency | | |
| Style | | |
| Safety | | |
| **Total** | **/50** | **[x100/50]** |

### Issues Found
1. [Specific issue with location]
2. [Specific issue with location]

### Refinements Applied
- [Change 1 and rationale]
- [Change 2 and rationale]

Example Interaction

Input: "Refine this Python script."

Iteration 1 Evaluation:

• Functionality: Good
• Efficiency: Poor - uses nested loops for matching
• Style: Variable names a and b are unclear
• Score: 60/100

Refinements applied:

• Flattened loops using a set lookup (O(n))
• Renamed a to users, b to active_ids
• Added type hints

Iteration 2 Evaluation:

• Functionality: Good
• Efficiency: Excellent
• Style: Good
• Score: 95/100

Result: Present the refined script.

Evaluation Criteria

Quality rubrics, scoring frameworks, and convergence patterns for the evaluator-optimizer workflow. Use these criteria when evaluating code, documentation, or designs during refinement cycles.

Code Quality Rubric

Readability

What to check:

• Variable and function names describe their purpose
• Functions are short and do one thing
• Complex logic has explanatory comments (why, not what)
• Consistent formatting and indentation
• No deeply nested conditionals (max 3 levels)

Performance

What to check:

• Algorithm complexity matches the problem size
• Database queries are batched, not in loops
• Large data structures are not copied unnecessarily
• Hot paths avoid allocations
• Caching is used where data is expensive to compute and stable

Security

What to check:

• All user input is validated and sanitized
• Authentication and authorization are enforced consistently
• Secrets are not hardcoded or logged
• SQL queries use parameterized statements
• File paths and URLs are validated against traversal attacks
• Error messages do not leak internal details

Maintainability

What to check:

• Code follows single responsibility principle
• Dependencies are injected, not hardcoded
• Tests cover the critical paths
• Changing one module does not require changes in unrelated modules
• Configuration is externalized, not buried in code

---

Documentation Scoring

Accuracy

What to check:

• Code examples compile and run correctly
• API endpoints, parameters, and return values match the implementation
• Version-specific information is labeled with versions
• No outdated screenshots or references

Clarity

What to check:

• Jargon is defined on first use
• Sentences are concise (under 25 words preferred)
• Each section has a clear purpose
• Examples appear immediately after concepts
• Headings form a scannable outline

Completeness

What to check:

• All public APIs/functions are documented
• Error scenarios are documented with recovery steps
• Prerequisites and setup are covered
• Examples cover basic and advanced usage
• FAQ or troubleshooting section addresses common issues

Accessibility

---

Design Evaluation

Usability

What to check:

• Primary actions are immediately discoverable
• Error states provide clear recovery paths
• Forms have sensible defaults and validation
• Navigation structure matches the user's mental model
• Onboarding guides new users to their first success

Consistency

What to check:

• Same action has the same visual treatment everywhere
• Spacing, typography, and colors use design tokens
• Interaction patterns are predictable (same gesture = same result)
• Terminology is consistent across the interface
• Icons have consistent meaning and style

Accessibility (Design)

---

Iteration Patterns

Diminishing Returns

Each iteration should produce measurable improvement. Track the score delta:

If delta drops below 2 for two consecutive iterations, stop. Further iteration is unlikely to yield meaningful improvement.

Common Iteration Sequence

For code refinement, address issues in this order:

1. Correctness first: Fix bugs and logic errors. 2. Security second: Close vulnerabilities. 3. Readability third: Rename, restructure, simplify. 4. Performance fourth: Optimize hot paths. 5. Style last: Polish formatting, comments, conventions.

For documentation refinement:

1. Accuracy first: Fix incorrect information. 2. Completeness second: Fill gaps in coverage. 3. Clarity third: Simplify language, improve examples. 4. Accessibility last: Structure, links, alt text.

---

Convergence Criteria

When to Stop

The evaluator-optimizer loop should terminate when any of these conditions are met:

Quality Gate Template

Before declaring an artifact "done", verify:

## Quality Gate

- [ ] Correctness: All tests pass, logic verified
- [ ] Security: No known vulnerabilities, inputs validated
- [ ] Readability: A new team member can understand this in 5 minutes
- [ ] Performance: No O(n^2) or worse in common paths
- [ ] Style: Matches project conventions
- [ ] Documentation: Public interfaces are documented
- [ ] Edge cases: Null, empty, max, concurrent scenarios handled

Overall score: __/100
Iterations completed: __
Recommendation: [SHIP / NEEDS REVIEW / NEEDS REWORK]

---

Artifact-Specific Checklists

Code Refinement Checklist

• [ ] All functions have a single, clear purpose
• [ ] No duplicated logic (DRY but not over-abstracted)
• [ ] Error paths are handled, not swallowed
• [ ] Types/contracts are explicit at module boundaries
• [ ] Tests cover happy path and at least 2 edge cases per function
• [ ] No TODO or FIXME comments remain (resolved or tracked)

Documentation Refinement Checklist

• [ ] Every code example is tested and works
• [ ] All sections flow logically (no forward references without links)
• [ ] Prerequisites are stated upfront
• [ ] Troubleshooting covers the top 3 failure modes
• [ ] Language is direct: no "basically", "simply", "just"

Design Refinement Checklist

• [ ] All states are designed (loading, empty, error, success, disabled)
• [ ] Color contrast passes WCAG AA (4.5:1 for text, 3:1 for large text)
• [ ] Touch targets are at least 44x44px
• [ ] Focus order is logical and visible
• [ ] Animations respect prefers-reduced-motion