Harness Engineering Practices P20. Make Legibility and Calibrated Uncertainty an SLO 🎯 Point Now that generation is cheap, the real bottleneck is "human review time." Diffs should be optimized not just for correctness, but for reviewability. 📝 Overview Optimize diffs for review time, not just correctness. Small, focused PRs. Explanations that tell "why." Explicit flagging of risky areas. Additionally, have the agent explicitly output "areas of low confidence" so the harness can route them to additional verification or human review. Calibrated uncertainty is more valuable than false confidence. 🔍 Explanation As agent generation speed increases, the bottleneck shifts from "writing code" to "reviewing code." Giant PRs, unexplained changes, confidently-presented but actually uncertain implementations — these explosively consume reviewer time. Treating legibility as an SLO (Service Level Objective) and measuring/optimizing PR size, explanation presence, and change rationale improves overall throughput. Having agents explicitly state "I'm not confident here" and "this needs human verification" lets reviewers focus on what matters. This is the most overlooked practice for building trustworthy autonomous agents. 🛠 How to Practice - Add "change rationale," "confidence level (high/medium/low)," and "review focus areas" fields to PR templates and require the agent to fill them - Set PR size limits and force splitting when exceeded - Require "low confidence" markers in agent output so the harness can route those areas to additional verification - Measure review time per PR and identify causes of long reviews (giant diffs, missing explanations, etc.) for improvement 💼 Use Cases - Issue-to-PR agents including change rationale and confidence markers in PRs - Code review agents suppressing low-confidence trivial comments and focusing on types humans miss - Migration: keeping per-unit PRs small and focused to distribute reviewer load ⚠ Pitfalls Over-optimizing for legibility can make agent output overly conservative. "Uncertainty expression" can also become noise — an agent that says "I'm not confident" about everything is useless. Calibration is key: accurately marking only genuinely uncertain areas is what creates value. Don't forget to measure review time either. Quantitatively tracking whether PR spam or giant diffs are crushing review bandwidth is the starting point for improvement. #HarnessEngineering# #CodeReview#