orchestrate-naming-and-structurelisted

# Orchestrate: Naming and Structure **Direct evidence**: HackerRank's guidance is explicit — code *"should be runnable and readable. Anyone should be able to open it, find the entry point, understand the main flow."* Named mistakes: *"Poor naming: Don't use generic filenames like 'helper' or 'utils'—use descriptive names reflecting file purpose."* Named recommended practice: *"Separate concerns clearly: input loading, prompts, agent logic, validation, evaluation."* ## The five concerns, kept separate The organizer's own list is the checklist: | Concern | What lives here | What doesn't | |---|---|---| | **Input loading** | Reading the corpus/CSVs, parsing tickets/claims into structured objects | Any decision-making logic | | **Prompts** | The actual prompt templates, versioned and readable as text | Business logic that decides *which* prompt to use | | **Agent logic** | The loop: decide next action, call tools, interpret results | Prompt text, validation rules | | **Validation** | Schema checks, enum checks, the guardrail pattern from `orchestrate-schema-guardrails` | Agent decision-making | | **Evaluation** | Comparing output against `sample_*.csv`, computing metrics | Production agent code | A codebase where these five are tangled into one 400-line `main.py` fails this check even if it produces correct output — because "correct output" is only 30-60% of what's being scored (code quality is a separate 30%, and the interview probes architecture directly). ## Naming: the