Don't Let Claude Haiku Do the Math — A Two-Stage Read-Aloud Coach Design, and the Prompt Swamp

📝 Originally published in Japanese on Zenn. This is the English version. Canonical: https://zenn.dev/uya0526_design/articles/satellite2_haiku-coaching 📚 This is satellite article #2 in my "Read-Aloud Speed Meter dev log" series. For the whole picture, see the main article ; for the AmiVoice integration, see satellite #1 . Where This Sits This article covers the part of the read-aloud speed meter that hands the measured numbers to Claude Haiku to generate coaching as "one compliment + one improvement." Many articles that use generative AI just dump it on the model: "here's the recognized text, evaluate it nicely." This article is the opposite. Don't let the LLM do the math. All computation and rule-based decisions are settled in code, and Haiku only does the wording. I'll go through how I designed this "two-stage" split, and which swamps I sank into during implementation. Four things: Why "code does the math, Haiku only does the wording" (the role-split design) The finalized prompt, and the messages / system / cache_control implementation First-hand findings: the prompt cache that didn't work The moment real data slapped me with "written in the prompt ≠ obeyed" 💡 I'm an ex-Java engineer learning TypeScript in public, so I drop in Java comparisons. Why Not Let Haiku Do the "Math"? Up front: Haiku is more than enough for feedback generation — in fact, you can shape the task into something Haiku is good at. The key is the role split. I settle all the metric computation (speaking speed, stagnation rate, threshold decisions) entirely in code. So by the time it reaches Haiku, it's already settled facts like this (below is from running labelMetrics on a real measurement — reading the Heike sample during development; stagnationRate is a number for percentage display): { "pureSpeakingSpeed" : 322 , "pureSpeakingSpeedEvaluation" : "slightly fast" , "stagnationRate" : 0 , "stagnationRateEvaluation" : "few" } Haiku's only job is to translate these numbers and labels into warm, c