eval

<core_principles>

1. DEFINE BEFORE CODE: Evals written first force clear thinking about success criteria.
2. CODE GRADERS > MODEL GRADERS: Deterministic checks beat probabilistic judgments.
3. STRUCTURAL SEPARATION FOR HIGH-STAKES: When stakes are real (security, payments, eval-of-evals, agent quality scoring), use the blind-evaluator agent — never self-score. Self-scoring inflates results ~36% structurally; procedural separation ("I won't peek") does not fix it.
4. TRACK PASS@K: pass@1 (first attempt), pass@3 (within 3 attempts). Target pass@3 > 90%.
5. REGRESSION BEFORE SHIP: Every change must pass existing evals before merge.
6. FAST EVALS GET RUN: Slow evals get skipped. Keep evaluation fast. </core_principles>

<blind_evaluation_protocol> Use when implementing agent would otherwise score its own output (high-stakes: security, payments, agent quality):

1. Spawn agents/blind-evaluator.md as a fresh agent.
2. Pass ONLY: problem statement, rubric (3-7 criteria with PASS conditions + weights), artifact path.
3. Do NOT pass: implementer's checkpoint, summary, commit message, prompt, or expected solution.
4. (gate: blind evaluator runs contamination check — if forbidden inputs detected, returns INVALID; clean inputs and retry)
5. (gate: confidence < 0.7 from blind evaluator → escalate to human grader)

Two-phase eval protocol:

• Run 1: implementing agent solves cold, no eval feedback. Blind evaluator scores. This is the externally-reportable number.
• Run 2: implementing agent gets Run 1 score + rubric breakdown, then optimizes. For iteration only. </blind_evaluation_protocol>

pass^k: "All k trials succeed"

• pass^3: 3 consecutive successes
• Use for critical paths (auth, payments)

See reference for calculation formula and worked examples.

<grader_selection>

1. Code-based (preferred): grep, test suite, build, type-check — deterministic, fast.
2. Model-based: for open-ended outputs that can't be checked deterministically. Run multiple times, take majority.
3. Human: required for security-sensitive changes, UX evaluation, legal/compliance.

See reference for full grader templates and examples. </grader_selection>

<anti_patterns> Writing evals after implementation tests existing bugs, not requirements. Model-based grading is slow and probabilistic. Prefer code graders. Every change must pass regression evals. No exceptions. Evals that take > 30s get skipped. Keep them fast. Track pass@k over time. Declining reliability is a signal. For any user-facing or high-stakes eval, the implementing agent scoring its own work inflates results ~36%. Spawn blind-evaluator instead. Evaluating against a codebase that already contains the canonical solution = answer key in the eval set. Use pre-merge snapshots or a separate fixture. Greenfield tickets in the golden eval set collapse to self=10, blind=3. Greenfields are not evaluable as solved tasks — exclude them from the dataset. Optimizing how much context the evaluator gets before establishing a baseline score = can't distinguish signal from noise. Run minimal-context baseline first, then test additions one at a time. </anti_patterns>