This is the heart of the Compendium. Scan stems for these phrases; the right answer is usually adjacent.
Volume / scale / cost tells
| Stem says | Pick |
|---|---|
| "X/sec" or "millions/day" + "cost critical" | Simplest pattern — single LLM call, smaller model |
| Real-time + sub-100ms latency + finite rules | NOT an LLM at all — deterministic code; reserve LLM for ambiguous edge cases |
| High volume + binary classification | Single classifier; gate voting/eval-opt to low-confidence subset |
| "Cost spiked" + "tokens loaded every session" | Workspace scope fix (.claudeignore or subdirectory CLAUDE.md, or .claude/rules/ with paths:) |
Trust level tells
| Stem says | Pick |
|---|---|
| "Untrusted external PRs", "external contributors", "untrusted input" | Read-only allow list, deny everything else, sandboxed, --max-turns |
| "Internal trusted service" | Least-privilege for workflow needs (NOT full lockdown) |
| "User-supplied input from internet" | Structured separation (XML tags) + filter + minimize blast radius |
"Already tried" tells (the big one)
| Stem says | Pick |
|---|---|
| "Team already tried prompt + few-shot, plateaued" | Code-level enforcement (programmatic prerequisite, tool-dispatch gate) |
| "Tightening the system prompt didn't help" | Structural pattern (tool use schema, hook, idempotent tool design) |
| "Switched to Opus, still failing" | Architecture issue, not model size |
| "Added more examples, still drifting" | Schema/validation/retry at the consumer side |
Path / structure tells
| Stem says | Pick |
|---|---|
| "Path varies wildly", "sometimes 3 steps, sometimes 30", "branches mid-execution" | Full agent with bounded stop conditions |
| "Same fixed sequence every time" | Prompt chaining workflow |
| "Lead reads input and dynamically decides count/identity of workers" | Hub-and-spoke (orchestrator-workers) |
| "Three always run in parallel, fixed roles" | Parallelization with specialized workers |
| "Classifier picks ONE of N handlers; only one runs per input" | Routing |
| "Generator → evaluator → retry until pass" | Evaluator-optimizer |
| "Subagents AS TOOLS, called sequentially" | Single agent with subagent tools (NOT hub-and-spoke) |
Composition tells
| Stem says | Pick |
|---|---|
| "What is the PRIMARY pattern?" | Identify OUTERMOST coordination |
| Outer routing + nested chains | PRIMARY = routing |
| Outer chain + routing-inside-one-step | PRIMARY = chain |
| Outer hub-and-spoke + eval-opt inside each worker | PRIMARY = hub-and-spoke |
| Hierarchical orchestrators delegating to mini-orchestrators | Hierarchical hub-and-spoke |
Anti-pattern alarm bells
| Stem language | Diagnosis |
|---|---|
| "Agents collaborate freely / debate / negotiate / collectively decide" | Peer-to-peer = anti-pattern; push back |
| "Multi-agent debate / discussion / refinement loop where agents critique each other" | Peer-to-peer in disguise |
| "Add a moderator agent to peer-to-peer" | Still peer-to-peer; doesn't fix structure |
| "Adaptive workflow that dynamically decides" | Could be chain-with-conditionals OR agent; check whether structure is fixed |
| "Hybrid system where N agents communicate freely" | Peer-to-peer; suggest hub-and-spoke instead |
Stop condition tells
| Stem says | Pick |
|---|---|
| "Burned $X, ran for hours, killed manually" | Missing stop conditions (max iter, cost cap, error threshold) |
| "Loop iterating 9-15+ times with diminishing returns" | Bound iterations + graceful fallback |
| "Persistent malformed input → infinite retry" | Bounded retry + graceful failure + log |
Confidence / hallucination / handoff tells
| Stem says | Pick |
|---|---|
| "Confidently produces wrong answers on edge cases" | Confidence labels + routing to verification / human |
| "Hallucinated fields / extra keys in JSON" | Tool use strict schema (eliminates by enforcement) + validation/retry |
| "Hallucinated facts not in source" | Grounding evaluator step (verify each claim against source) |
| Agent escalates with "I need help with this ticket" | Structured handoff package (goal, steps taken, why escalating, recommendation) |
Long-conversation drift tells (high-yield, real-exam tested)
| Stem says | Pick |
|---|---|
| "Turn 20+, specific facts ($847.50, March 3rd, TXN-ID) became vague" | Persistent Case Facts Block at top of every prompt |
| "Recent context essential AND earlier decisions still matter" | Summarization (NOT RAG) |
| "Large external knowledge base (50,000 pages)" | RAG |
| "Cross-session, model forgets prior session" | Application-level memory (persisted history or summary doc) |
| "Carry session conclusions into a clean window without losing prior work" | Fork-the-session pattern — branch from the current state so noisy tool output drops away while findings persist into the new window |
| "Two divergent paths from shared session foundation" | fork_session |
Multi-agent decomposition tells
| Stem says | Diagnosis |
|---|---|
| "47 sub-tasks → slow, expensive, synthesizer can't combine" | Over-decomposition |
| "Single sub-agent overwhelmed, low-quality output, context overflow" | Under-decomposition |
| "Sub-agents produce overlapping findings" | Decomposition flaw (overlapping scopes) |
| "Sub-agent fails silently, system returns incomplete" | Orchestration flaw (no error handling) |
| "Sub-agent ignored parent goal, went off-topic" | Decomposition flaw (insufficient context passed) |
| "One worker takes 60s, others 5s, all waited for" | Sync→async workers OR redesign slow worker |
Multi-agent decomposition tells
| Stem says / Need | Pick / Action |
|---|---|
| "Coordinator + workers share the same prompt; quality plateaus, all agents have the same blind spots" | Diversify per-role prompts and/or model variants; shared templates create shared failure modes |
Volume / scale / cost tells
| Stem says / Need | Pick / Action |
|---|---|
| "Pipeline runs out of memory on 500MB PDFs / large files" | Stream-process: chunk by page/section, write intermediates to disk, never load full document in memory |
| "Reproducible benchmark timing inside agent skill / code-execution sandbox" | Dedicated runner + fixed CPU allocation + isolated env + controlled GC + multiple runs with statistical aggregation; not a Claude/LLM concern |
Long-document architecture tells
| Stem says | Pick |
|---|---|
| "Document exceeds context window" / "1,200-page contract" | Chunk + extract per chunk + merge at consumer (overlap; respect section boundaries) |
| "Need to find X across the whole long document" (liability clauses, themes) | Parallel section reviewers → consumer-side deduplication |
| "Section alone exceeds budget" | Recursive chunking — split until each chunk fits |
| "Tables / code blocks / footnotes interspersed" | Structure-aware chunker — preserve semantic boundaries; fall back to fixed windows only for prose |
| "Chunker splits mid-sentence" | Sentence/paragraph-boundary chunker + overlap |
RAG tuning tells
| Stem says | Pick |
|---|---|
| "Retrieving N chunks, synthesis mediocre / lost in the middle" | Reduce k, rerank by relevance, place top-ranked at start OR end (not middle) |
| "Vector retrieval misses different-wording / different-phrasing answers" | Hybrid retrieval (vector + BM25) + query rewriting + rerank |
| "Retrieval drift after corpus expansion / quality dropped after adding docs" | Re-evaluate retrieval thresholds, monitor precision@k; new overlaps shift rankings |
| "Same query → different chunks / inconsistent answers across runs" | Deterministic retrieval ordering + corpus dedup + SME reconciliation for genuine conflicts |
| "Embedding lookups bottleneck at concurrent scale" | Vector DB indexing (HNSW/IVF) + horizontal scale + query cache + embedding-server pool |
Progressive summarization (active-vs-resolved distinction)
| Stem says / Need | Pick / Action |
|---|---|
| 'Multi-issue session approaching context limit AND active issue still in progress' | Progressive summarization: condense resolved sub-issues into compact recaps; keep the currently-active issue's full message history verbatim |