When Agent consistently selects the wrong tool among similar options → Review and expand tool descriptions FIRST -- include input formats, example queries, and boundary explanations.

When Two tools have near-identical names/descriptions causing misrouting → Rename the tools and rewrite descriptions to clearly distinguish each tool's purpose.

When Tool descriptions are clear but the agent still misroutes based on keywords like 'account' → Review the system prompt for keyword-sensitive instructions that create unintended tool associations.

When A tool encounters a transient failure (timeout, service unavailable) → Return isError: true with errorCategory: 'transient', isRetryable: true, and what was attempted.

When A business rule is violated (e.g., refund exceeds policy limit) → Return isError: true with errorCategory: 'business', isRetryable: false, and a customer-friendly explanation.

When A query returns zero results but executed successfully → Return a success response (isError: false) with empty results -- do NOT treat this as an error.

When A specialized agent misuses tools outside its role (e.g., doc analysis agent doing web searches) → Replace generic tools with purpose-specific constrained alternatives (e.g., fetch_url -> load_document).

When 85% of a subagent's verification needs are simple fact-checks with 15% complex → Give a scoped verify_fact tool for simple lookups; route complex cases through the coordinator.

When You need to guarantee the model calls a specific tool first in a sequence → Use tool_choice: {'type': 'tool', 'name': 'extract_metadata'} for the first turn, then switch to 'auto'.

When Team needs shared MCP tooling with per-developer credentials → Use project-scoped .mcp.json with ${ENV_VAR} expansion for tokens; document required vars in README.

When A developer wants to experiment with a personal MCP server → Configure it in user-scoped ~/.claude.json so it does not affect teammates.

When A standard integration exists (GitHub, Jira) and you are considering a custom server → Use the existing community MCP server; reserve custom implementations for team-specific workflows.

When You need to find all callers of a specific function across the codebase → Use Grep to search file contents for the function name.

When You need to find all test files regardless of directory location → Use Glob with pattern **/*.test.tsx to match by naming convention.

When Edit fails because the anchor text appears multiple times in the file → Use Read to load full contents, then Write the modified version as a fallback.

When A guideline must apply to all team members (current and future) → Place it in project-level .claude/CLAUDE.md or .claude/rules/, NOT in user-level ~/.claude/CLAUDE.md.

When CLAUDE.md exceeds 400+ lines mixing multiple concerns → Split into topic-specific files in .claude/rules/ (e.g., testing.md, api-conventions.md).

When A new team member is not receiving project guidelines → Verify the guideline exists in project-level config, not just in existing developers' user-level config.

When A skill produces verbose output that causes Claude to lose track of the original task → Add context: fork to the skill's frontmatter to run in an isolated sub-agent context.

When A developer wants a personal variant of a team skill without affecting teammates → Create a personal skill in ~/.claude/skills/ with a DIFFERENT name (project skills shadow same-named personal ones).

When Context is only useful for a specific workflow (e.g., endpoint generation) and not general work → Create a skill with the exemplar code; invoke on-demand via slash command instead of putting it in CLAUDE.md.

When Different coding conventions apply to different file types (React components vs API handlers vs tests) → Create .claude/rules/ files with YAML frontmatter paths glob patterns for each file type.

When Test files are spread throughout the codebase alongside source files → Use path-specific rules with **/*.test.tsx glob rather than subdirectory CLAUDE.md files.

When You want conventions to apply to terraform files in any directory → Use paths: ['terraform/**/*'] in rule frontmatter instead of a terraform/CLAUDE.md file.

When Task involves ambiguous requirements with multiple valid integration approaches (e.g., adding Slack support) → Enter plan mode to explore options and architectural implications before implementing.

When Task is a well-understood change with clear scope (e.g., bug fix with a clear stack trace) → Use direct execution -- no need for plan mode.

When Discovery phase generates verbose output that fills the context window → Use the Explore subagent to isolate verbose output and return a concise summary to the main conversation.

When Claude interprets prose requirements differently each iteration, producing inconsistent output structure → Provide 2-3 concrete input/output examples showing the expected transformation.

When You are implementing in an unfamiliar domain and want to surface edge cases → Use the interview pattern: have Claude ask about design considerations before implementing.

When Multiple bugs interact with each other → Describe all interacting issues in a single message rather than fixing them sequentially.

When Running Claude Code in an automated CI pipeline → Use the -p flag for non-interactive mode; use --output-format json with --json-schema for structured output.

When The same Claude session generated code and you need a review → Use a second, independent Claude instance without access to the generator's reasoning context.

When Re-running review after developer pushes fixes, and getting duplicate findings on already-fixed code → Include prior review findings in context, instructing Claude to only report new or still-unaddressed issues.

When Automated review produces high false positive rates that erode developer trust → Temporarily disable high false-positive categories; keep only high-precision categories while improving prompts.

When Severity ratings are inconsistent across similar issues → Add explicit severity criteria with concrete code examples for each level, not general 'be conservative' instructions.

When A prompt instruction is vague (e.g., 'check comments are accurate') → Replace with explicit criteria defining exactly what constitutes a problem (e.g., 'flag only when claimed behavior contradicts code').

When Detailed format instructions produce variable output quality (sometimes detailed, sometimes vague) → Add 3-4 few-shot examples showing the exact desired format with issue, location, and specific fix.

When Agent misroutes between tools on ambiguous requests → Add 4-6 few-shot examples targeting ambiguous scenarios, each showing reasoning for the tool choice.

When Agent handles individual concerns well (94%) but fails on multi-concern messages (58%) → Add few-shot examples demonstrating correct reasoning and tool sequencing for multi-concern requests.

When You need guaranteed structured output with no JSON syntax errors → Define an extraction tool with JSON schema as input parameters; extract data from the tool_use response.

When Multiple extraction schemas exist and the document type is unknown → Set tool_choice: 'any' to guarantee a tool call while letting the model choose which extraction schema.

When Source documents may not contain all required fields → Design those schema fields as optional (nullable) to prevent the model from fabricating values.

When Extraction output has format or structural errors (wrong nesting, bad date format) → Retry with the original document, the failed extraction, and specific validation errors appended.

When Required data simply does not exist in the source document → Do NOT retry -- retries cannot conjure missing information. Accept null/empty or flag for human review.

When Developers frequently dismiss automated findings and you want to improve accuracy → Add detected_pattern fields to structured findings to track which constructs produce false positives.

When Workflow is latency-sensitive and blocks developers (pre-merge checks) → Use synchronous API calls, NOT batch processing.

When Workflow is scheduled and latency-tolerant (overnight reports, weekly audits, nightly test generation) → Use Message Batches API for 50% cost savings.

When Workflow requires iterative tool calling (analyze file, request related files, continue analysis) → Do NOT use batch processing -- it cannot execute tools mid-request and return results.

When Claude-generated code has subtle issues that only surface during human peer review → Use a second, independent Claude instance to review without access to the generator's reasoning.

When Single-pass review of many files produces inconsistent depth and contradictory feedback → Split into per-file local passes plus a separate cross-file integration pass.

When Developers spend too much time investigating each finding to decide if it is real → Require Claude to include reasoning and confidence assessment inline with each finding.

When Customer references specific amounts ('the 15% discount I mentioned') that were summarized away → Extract transactional facts (amounts, dates, order numbers) into a persistent 'case facts' block outside summarized history.

When Synthesis agent omits critical findings from the middle of 75K+ token aggregated input → Place a key findings summary at the beginning; organize the rest with explicit section headers.

When Tool outputs return 40+ fields per lookup when only 5 are relevant → Trim verbose tool outputs to only relevant fields before they accumulate in context.

When Policy is ambiguous or silent on the customer's specific request (e.g., competitor price matching) → Escalate to a human for policy interpretation -- do not fabricate a policy.

When get_customer returns multiple matches and the agent guesses wrong 15% of the time → Instruct the agent to ask for an additional identifier before taking any customer-specific action.

When The issue is straightforward but the customer explicitly asks for a human agent → Escalate immediately -- honor the explicit request without attempting to resolve first.

When A subagent encounters a timeout (transient failure) → Attempt local recovery; if it fails, propagate structured error context (failure type, what was attempted, partial results) to the coordinator.

When A subagent encounters a corrupted file (permanent failure) → Return the error with context to the coordinator -- do NOT retry (corruption is permanent).

When Some source categories succeed while others fail in a multi-source research task → Proceed with available data; annotate synthesis output with coverage gaps indicating which sources were unavailable.

When Discovery phase generates verbose output that fills the main context window → Use the Explore subagent or context: fork to isolate verbose output; return a concise summary.

When Extended exploration session shows signs of context degradation (vague references instead of specifics) → Have agents maintain scratchpad files recording key findings; use /compact to reduce context usage.

When Multi-phase task needs to persist findings across context boundaries → Summarize key findings from one phase before spawning sub-agents for the next; inject summaries into initial context.

When Overall accuracy is 97% but you suspect some document types perform poorly → Analyze accuracy by document type and field to identify hidden poor-performing segments.

When You want to reduce human review overhead on high-confidence extractions → Implement stratified random sampling of high-confidence outputs; only reduce review after validating by segment.

When Model outputs field-level confidence scores but they do not correlate with actual accuracy → Calibrate confidence thresholds using labeled validation sets rather than trusting raw model scores.

When Two credible sources report conflicting statistics on a key metric → Include both values with explicit source attribution; let the coordinator decide how to reconcile before synthesis.

When Subagent outputs are compressed and downstream agents lose track of which claims came from where → Require subagents to output structured claim-source mappings (source URLs, document names, excerpts).

When Data from different time periods appears contradictory → Require publication/collection dates in structured outputs to enable correct temporal interpretation.