Run: 018 · Date: 2026-05-06 · Phase 5 author · Assignment: Glossary for Humans
The Next Chapter codebase has 25+ technical concepts that Charlie and Bear will encounter while building features. After reading every relevant source file (permissions.ts, circuit-breaker.ts, tickets.ts, handoff.ts, the feature definitions in defs/, the webhook routes, and the alert system), I produced a 27 entry glossary, a 5 cluster concept map, and translations of the 9 most likely error messages. Every translation is grounded in what the code actually does, not abstract definitions. The glossary avoids teaching computer science. It tells Charlie and Bear: what is this thing, why does it exist, and where will you bump into it.
I do not know what error messages the UI actually renders to the user. I read the backend functions that generate errors and reasons (like gateReason() in permissions.ts), but I have not seen the React components that display them. If the frontend wraps these in different language, the error translations below may not match what Charlie and Bear actually see on screen. A follow up pass through the UI components would close this gap.
Across runs 003, 008, and now 018, the recurring pattern is: the system's vocabulary splits into two worlds. The code speaks in short function names (canUse, checkBudget, isPromotable) that are clear to engineers but opaque to interns. The UI speaks in labels ("View Meetings List", "Promote to Deal") that are clear to users but disconnected from the code vocabulary. This glossary bridges the two. Charlie and Bear will hear both vocabularies when reading code with Claude Code, and they need a lookup table to connect them.
This run forced me to translate a complete system, not just spot check a report for leaked jargon. The difference: when you translate one report, you can substitute words in isolation. When you translate an entire architecture, you have to explain how concepts connect to each other. The concept map was harder than the glossary because it required showing relationships, not just definitions. Going forward, I will produce a concept map alongside any glossary, because isolated definitions without connections leave the reader stranded. I also learned that error messages are the most important translation target. Charlie and Bear will not read the glossary for fun. They will read it when they hit a wall and need to understand what happened. The error translation table is where this glossary will earn its keep.
Generated from 018__tech-translator.md — do not edit this HTML directly.