Home › Certifications › CCA-F › Mind maps

Claude Certified Architect, Foundations · revision sheet

CCA-F mind maps: every decision table in one place

Every question in mock exams 4 to 7 ends with a mind map: a small table that says what you see, what is really wrong, and which fix fits. Many questions shared the same kind of decision, so their tables have been merged. That turns 240 tables into 83 mind maps, each named by the decision it helps you make.

1. Find the decisionRead the "Mind map for" column below and pick the one that matches the question in front of you.
2. Match the symptomIn the table, find the row that describes what the question tells you. The fix in that row is usually the answer.
3. Check the neighbour rowThe row next to it is often the runner-up option. Find the sentence in the question that rules it out.

Which mind map is for what

No.Mind map forAsk yourselfObjective
Domain 1: Agentic architecture and orchestration
1Fixed sequence or model-driven loopIs the path known in advance, or does each step depend on what was just found?1.1 Agentic loops
2When an agent loop should continue or stopWhich signal is the loop reading to decide it is done?1.1 Agentic loops
3Why an agent repeats calls or forgets what it foundWhat is missing from the history the loop sends back to the model?1.1 Agentic loops
4Why Claude talks about stale or out-of-date codeIs Claude reasoning from an old tool result, or from a context that has degraded?1.1 Agentic loops
5Finding where a research report's gap startedWhen could the missing area first have been seen: in the request itself, or only after reading the sources?1.2 Coordinator and subagents
6Cutting waste in a slow or costly multi-agent pipelineWhich waste is biggest: unneeded subagents, overlapping work, needless sequencing or real-time pricing?1.2 Coordinator and subagents
7When one subagent needs another subagent's helpCan this request change the plan, or is it a simple, frequent need?1.2 Coordinator and subagents
8Whether to hand work to a subagent at allWould delegating isolate verbose output or run independent work in parallel?1.3 Subagent invocation and context passing
9Where each piece of a subagent's context belongsDoes this information change per run, and where must it be written so the subagent actually sees it?1.3 Subagent invocation and context passing
10Why a subagent's output is weak, generic or missingWhich step of delegation failed: spawning, choosing the subagent, briefing it, or the inputs it was given?1.3 Subagent invocation and context passing
11Speeding up a slow multi-agent runIs the time going on needless sequencing, unneeded subagents, or a real dependency?1.3 Subagent invocation and context passing
12How to brief a coordinator agentDo questions arrive in new shapes, or are they known, stable types?1.3 Subagent invocation and context passing
13Prompt or code for a rule that must holdWhat does one miss cost: is this a must-always rule or a should-usually one?1.4 Multi-step workflows, enforcement and hand-off
14Which control enforces an order or forces a tool callDo you need to block a wrong call, force one call on one turn, or enforce an order across a whole session?1.4 Multi-step workflows, enforcement and hand-off
15Organising a request that raises several concernsAre the concerns lost in the first reply or many turns later, and how heavy is each one?1.4 Multi-step workflows, enforcement and hand-off
16Handing work over to a human or a later sessionWho picks the work up next, and what do they need to read first?1.4 Multi-step workflows, enforcement and hand-off
17Fixing a gate that blocks a legitimate caseCan the proof be seen in tool data, so the gate can learn a second kind of proof in code?1.4 Multi-step workflows, enforcement and hand-off
18Hard stop, cleanup or nudge: which control acts at the right momentMust the rule hold every time, and does it act on the outgoing call or on the result?1.5 Agent SDK hooks
19Where to fix messy, sensitive or derived tool dataDo you control the source, and is the job deterministic enough for code?1.5 Agent SDK hooks
20When a hook exists but the policy still breaksWhat does the hook actually check, and does that match what the policy is about?1.5 Agent SDK hooks
21Fixed chain or adaptive decomposition for a multi-step jobCan the steps be listed before the work starts, or does reading reveal new work?1.6 Task decomposition
22Making agent runs faster or cheaperDoes each request need the full pipeline, and is anyone waiting for the answer?1.6 Task decomposition
23Strategy for understanding unfamiliar codeDo you need the answer to one specific question, or a broad map of a large area?1.6 Task decomposition
24Splitting one growing promptIs the problem where items sit in the prompt, or that one prompt can't fit every kind of input?1.6 Task decomposition
25Resume, fork or start fresh when continuing old workIs the earlier session still accurate, and do you want one line of work or two?1.7 Session state, resuming and forking
Domain 2: Tool design and MCP integration
26Claude picks the wrong tool: which lever to pull firstIs the tool description the problem, or is something else steering the choice?2.1 Tool descriptions and boundaries
27A tool is called with bad inputs: description, examples or a splitWhat was the model actually told about this tool and its inputs?2.1 Tool descriptions and boundaries
28What error to return for each kind of tool failureWhat does the agent need to know about this failure to recover from it?2.2 Structured tool errors
29Telling "found nothing" apart from "could not look"Did the tool look and find nothing, or could it not look at all?2.2 Structured tool errors
30What a failing subagent sends back to the coordinatorCan this failure be fixed locally, and if not, what does the coordinator need in order to decide?2.2 Structured tool errors
31Which tool_choice setting to useWhat may Claude still choose: text or a tool, which tool, or nothing at all?2.3 Tool distribution and tool_choice
32Too many tools, or the wrong tools, on one agentIs the agent confused among the right tools, or holding tools it shouldn't have?2.3 Tool distribution and tool_choice
33A subagent needs help from outside its roleWhat kind of outside help is it: a frequent simple check, or rare open-ended work?2.3 Tool distribution and tool_choice
34Controlling a risky tool: remove it, gate it, or guide itIs this action forbidden, allowed with approval, allowed under a limit, or just a preference?2.3 Tool distribution and tool_choice
35Reuse a community MCP server, describe conventions, or build your ownDoes something already exist for this system, and is the gap capability or just context?2.4 MCP servers in Claude Code and agents
36Where an MCP server's configuration livesWho needs this server, and how do they get it without a secret being committed?2.4 MCP servers in Claude Code and agents
37A better MCP tool is ignored or missingIs the MCP tool missing from Claude's list, or listed but losing to a built-in?2.4 MCP servers in Claude Code and agents
38Too many exploratory calls: what the agent is missingIs the agent calling tools to find out what exists, or because a tool is unclear?2.4 MCP servers in Claude Code and agents
39Which built-in tool to find and explore codeAre you matching names, searching contents, reading a file, or only after a conclusion?2.5 Built-in tools (Read, Write, Edit, Bash, Grep, Glob)
40Changing a file: Edit, replace_all, or Read and WriteIs the text you want to change unique in the file?2.5 Built-in tools (Read, Write, Edit, Bash, Grep, Glob)
Domain 3: Claude Code configuration and workflows
41Where a convention or instruction should live in the CLAUDE.md hierarchyWho needs this guidance, who owns it, and which files does it follow?3.1 CLAUDE.md hierarchy and scope
42Instructions ignored or missing for some people: diagnosing which memory file is at faultIs the guidance actually loaded, and if so, which file is it coming from?3.1 CLAUDE.md hierarchy and scope
43Sharing a command with the team versus keeping it personalWho needs the command, and how will it reach them?3.2 Slash commands and skills
44Command, skill, path rule or CLAUDE.md: choosing the home by when content should loadShould this load always, when certain files are edited, or only when someone asks?3.2 Slash commands and skills
45Controlling a skill: forked context, allowed tools and argumentsIs the problem what the skill can do, how much it puts into my context, or what input it needs?3.2 Slash commands and skills
46Path-scoped rules versus directory CLAUDE.md for file conventionsHow are the files this convention covers grouped: by pattern across folders, or inside one folder?3.3 Path-specific rules
47Plan mode, Explore subagent or direct execution for a changeWhat is still undecided about this change, and how wide is it?3.4 Plan mode or direct execution
48Examples, tests or interview: telling Claude what correct meansWhat do you already know about the right answer, and what kind of feedback is missing?3.5 Iterative refinement
49One message or several when you have multiple problemsDoes the fix for one problem depend on the outcome of another?3.5 Iterative refinement
50A CI step that hangs, ends empty or behaves differently from localWhich part of the invocation is wrong: mode, permissions, output shape or configuration scope?3.6 Claude Code in CI/CD
51Getting output in the shape its reader needs: schema, forced tool or format examplesWho reads the output, a program or a person, and through which interface?3.6 Claude Code in CI/CD
52Where CI-specific instructions live versus repo-wide onesWho needs these instructions: every session, one CI job, one developer, or some files?3.6 Claude Code in CI/CD
53Automated review misses things: reviewer, criteria or sizeIs the miss caused by who reviews, what they are told to look for, or how much they review at once?3.6 Claude Code in CI/CD
54Configuring several CI jobs: real-time, batch and turn limits per jobIs this job bound by latency, by cost, or does it need a tool loop?3.6 Claude Code in CI/CD
Domain 4: Prompt engineering and structured output
55Too many false positives: write criteria or add examplesIs the standard for a finding missing, or does it exist but get applied unevenly?4.1 Explicit criteria and false positives
56Fixing one noisy review category: rewrite, pause or measureThis one category keeps producing false positives: what kind of fix does it need?4.1 Explicit criteria and false positives
57Letting the model say it is unsure instead of guessingCan the model express doubt, or is it forced to commit to an answer?4.1 Explicit criteria and false positives
58Rules or worked examples when output is inconsistentAre the rules still vague, or are they clear but the hard cases keep varying?4.2 Few-shot examples
59Project conventions ignored: are the rules even loading?Are the rules actually loaded for these files, or loaded but described poorly?4.2 Few-shot examples
60Extraction across many document layouts: tailor, route or teachDo you know the layouts in advance, and are the field descriptions already clear?4.2 Few-shot examples
61Broken JSON or wrong value: what a schema does and doesn't catchIs the structured output wrong in its syntax, its format, or its meaning?4.3 Structured output and JSON schemas
62Value absent, unlisted or unreadable: which schema escape hatchWhat does the document actually say about this field: nothing, something the list doesn't cover, or something ambiguous?4.3 Structured output and JSON schemas
63Making the model call the right tool: tool_choice settingsMust the reply be a tool call, and if so, which tool exactly?4.3 Structured output and JSON schemas
64Validation failed: retry with feedback or hand off to a personIs the answer actually in the document for a retry to find?4.4 Validation, retry and feedback
65Catching tidy-but-wrong values: where the check must liveCould the model hide this mismatch, and what outside check can catch a wrong value that looks right?4.4 Validation, retry and feedback
66Measuring which review rules produce false positivesWho supplies the judgement of whether a finding was wrong: developer actions, or labelled samples?4.4 Validation, retry and feedback
67Batch or real-time: who is waiting, and by whenIs anyone blocked on the result or bound by a deadline, and does each item need a tool loop?4.5 Batch processing
68Working inside batch limits: tool calls, matching results, failuresWhat can a batch request not do, and how do you tie each result back to its input?4.5 Batch processing
69Cutting cost without losing coverageWhich cost levers keep the output complete?4.5 Batch processing
70Why a review misses bugs: self-review, dilution or unclear criteriaWhat shape are the misses, and what differs between a reviewer that finds them and one that doesn't?4.6 Multi-pass review
Domain 5: Context management and reliability
71Keeping exact facts intact through a long conversationWhat is losing the facts: the summary, the tool output, or where they sit?5.1 Keeping key facts in long interactions
72Getting the middle of a long input readWhere do the missed details sit, and is the input already structured?5.1 Keeping key facts in long interactions
73When the agent should hand over to a personWhich escalation trigger is actually present?5.2 Escalation and ambiguity
74Fixing an escalation boundary that misfiresWhat is the cheapest fix that makes the escalation boundary clear?5.2 Escalation and ambiguity
75Which customer record to act onWhat is the source of truth for who this customer is?5.2 Escalation and ambiguity
76Handling and reporting a subagent's failed or empty lookupDid the lookup actually run, and should the subagent handle the error itself or hand it up?5.3 Errors across agents
77What to do when a long session fills up or degradesIs the session just full, or has it degraded, and what is flooding it?5.4 Context in large codebases
78Carrying long work across a break, crash or handoverWhat carries the state forward: the conversation, a file on disk, or a fresh summary?5.4 Context in large codebases
79Keeping noisy search output out of the main contextIs the noise predictable enough to exclude, or does it need filtering somewhere else?5.4 Context in large codebases
80Proving a category is ready to skip human reviewWhich number do you actually have, and does it cover the category you plan to automate?5.5 Human review and confidence
81Finding where a citation lost its sourceAt which stage did the claim lose the link to its source?5.6 Sources, provenance and uncertainty
82Reporting figures when sources disagreeIs this a genuine conflict or a change over time, and what does the reader need?5.6 Sources, provenance and uncertainty
83Speeding up human review of extracted valuesWhere is the reviewers' time going, and what would save it?5.6 Sources, provenance and uncertainty

Domain 1: Agentic architecture and orchestration

1.1Agentic loops

Mind map 1 of 83 · for

1Fixed sequence or model-driven loop

Ask yourself: Is the path known in advance, or does each step depend on what was just found?

Reach for it when: You are deciding whether to script the tool calls in advance or let the model choose each one.

SituationDesignWhy
Same known steps every timeFixed sequence (prompt chaining)Predictable and auditable
Next step depends on what a tool returnedModel-driven loop on stop_reasonClaude chooses each call from the results
Several concerns in one messageDecompose, investigate each, answer allA multi-concern request needs every part covered
Workload mixes both kindsRoute known paths to sequences, the rest to the loopEach kind of work gets the design that fits it
Fixed tree shows no gain on any categoryKeep the loop everywhereScripting brings no benefit
Many lookups just to learn what existsMCP resource catalogFewer exploratory calls
Need to understand a code flowGrep entry points, then Read along the callsIncremental, not read-all

Rule to remember: Use a fixed sequence where the path is known in advance. When each step depends on the last result, let the model choose the tool calls and loop until stop_reason is end_turn.

Merged from 2 questions: Mock 7, scenario 4 question 10; Mock 5, scenario 1 question 9

Mind map 2 of 83 · for

2When an agent loop should continue or stop

Ask yourself: Which signal is the loop reading to decide it is done?

Reach for it when: The agent stops while a tool request is pending, stops mid-task after a set number of rounds, or never stops.

What you observeWhere the fault isFix
Run ends while a tool request is still pending, or the reply contains text and the tool request is droppedCompletion judged from the reply textContinue on stop_reason: "tool_use", stop on end_turn
Loop ends on phrases like “anything else?”Natural-language stop ruleBranch on stop_reason
Long, progressing tasks cut off after a fixed number of roundsIteration cap used as the main stopStop on end_turn; keep the cap only as a runaway guard
A structured “done” flag is used as the main stopThe flag is still model content, not an API signalUse stop_reason as the primary stop
Claude replies in prose with no tool request when a call was neededTool choice left at autotool_choice: "any" or a forced tool
Agent repeats the same calls until the capTool results not appended to historySend each tool_result with its matching id before the next request
Agent spins on a broken toolNo runaway protectionGenerous cap plus structured error handling
Steps fixed before any result is seenPre-set tool sequenceLet the model choose the next step from results

Rule to remember: One response can hold text and a tool call, so let stop_reason decide: on tool_use, run the tool and continue; on end_turn, stop. Reply text and step counts are not completion signals.

Merged from 4 questions: Mock 7, scenario 1 question 1; Mock 7, scenario 3 question 1; Mock 7, scenario 6 question 6; Mock 5, scenario 1 question 1

Mind map 3 of 83 · for

3Why an agent repeats calls or forgets what it found

Ask yourself: What is missing from the history the loop sends back to the model?

Reach for it when: The agent repeats calls, claims calls it never made, or loses facts and findings as the run gets longer.

What you observeWhere the fault isFix
Repeats calls, or claims calls it never madeAssistant tool_use turn not appendedAppend it, then the paired tool_result
Repeats calls in a short runTool results not appended to the messages listAppend each tool result to the conversation
Right calls, wrong details from resultsResults reworded or trimmed badlyReturn structured results
Exact amounts or dates blur, or facts are forgotten, only in long chatsProgressive summarisation, or lost in the middleCase-facts block; trim tool results
Loses findings in a long run near context limitsHistory too large to keepScratchpad file or subagent delegation
Picks the wrong toolWeak tool descriptionsExpand tool descriptions
Loop ends too early, too late or neverTermination check with no real stop signalUse stop_reason and end_turn, not text or an arbitrary cap

Rule to remember: The model knows only what you send. The history must hold each tool_use turn and its matching tool_result; drop either and the model loses track of what it has done.

Merged from 2 questions: Mock 7, scenario 3 question 6; Mock 4, scenario 1 question 9

Mind map 4 of 83 · for

4Why Claude talks about stale or out-of-date code

Ask yourself: Is Claude reasoning from an old tool result, or from a context that has degraded?

Reach for it when: Claude's answers are precise but out of date, or have turned vague and generic in a long session.

What you observeWhere the fault isFix
Precise but out of date after an outside editOld tool result in the historyTell Claude, or read the file again
Vague, inconsistent, “typical patterns”, in a long sessionContext degradationScratchpad notes, /compact, or a fresh session
Resuming a session after files changedStale results across sessionsSay what changed, or start fresh with a summary
Context filling with huge tool outputsVerbose resultsTrim outputs to the relevant fields
Middle of a long input ignoredLost in the middleKey facts at start or end, with headers

Rule to remember: A tool result is a snapshot in the conversation. If the file changes outside the session, say so or read it again.

Merged from 1 question: Mock 5, scenario 4 question 7

1.2Coordinator and subagents

Mind map 5 of 83 · for

5Finding where a research report's gap started

Ask yourself: When could the missing area first have been seen: in the request itself, or only after reading the sources?

Reach for it when: The final report misses a whole area or part of the question even though the subagents ran.

What you observeWhere the fault isFix
Whole area missing that the request itself implied; every subagent succeeded on its briefCoordinator's decomposition too narrowBroaden the decomposition; check coverage against the original request
Part was assigned but came back thin, or gaps surface only inside sources already readNo step checks the draft for gapsRefinement loop: evaluate the synthesis for gaps, re-delegate, re-synthesise
A subagent was asked about the area and came back emptySearch recall (queries)Improve the search queries or sources
Sources on the area were fetched, then vanishedAnalysis filteringFix the analysis brief or filter
Claims reached synthesis but were left outSynthesis rulesAdjust what synthesis keeps; report weak support instead of dropping
Subagent hit an error and returned partial resultsError not surfacedStructured error with partial results and the attempted query
Subagent ignores what earlier subagents foundContext not passedPut complete prior findings in its prompt
Two subagents cover the same groundOverlapping scopesPartition scope in the delegation

Rule to remember: Missing from the plan: widen the decomposition. Visible only after reading: fix it with a check-the-draft loop, not a bigger plan.

Merged from 3 questions: Mock 6, scenario 3 question 1; Mock 5, scenario 3 question 4; Mock 4, scenario 3 question 1

Mind map 6 of 83 · for

6Cutting waste in a slow or costly multi-agent pipeline

Ask yourself: Which waste is biggest: unneeded subagents, overlapping work, needless sequencing or real-time pricing?

Reach for it when: The pipeline is slow or expensive, or subagents seem to duplicate each other's effort.

What you observeWhere the fault isFix
Simple questions run every subagentFixed full pipelineCoordinator selects subagents by query complexity
Needed subagents fetch the same sources or redo each other's workOverlapping remitsPartition scope: named source classes and exclusions
Independent tasks run one after anotherNeedless sequencingParallel Task calls in one response
Later subagent genuinely needs earlier resultsReal dependencySpawn in sequence; pass complete prior findings
Work can wait hours (for example overnight) and cost mattersPaying real-time pricesMessage Batches API (50% cheaper, up to 24 hours)
Subagent misuses extra toolsOver-provisioningRestrict tools per role
Broad topic, whole areas missingDecomposition too narrowBroaden the decomposition
Claims cited to the wrong copy of a sourceAttribution, not costStructured claim-source metadata

Rule to remember: Size the pipeline to the question: the coordinator invokes only the subagents a request needs. Overlap between needed subagents is fixed by partitioning scope, not by dropping subagents.

Merged from 3 questions: Mock 6, scenario 3 question 4; Mock 5, scenario 3 question 2; Mock 5, scenario 3 question 8

Mind map 7 of 83 · for

7When one subagent needs another subagent's help

Ask yourself: Can this request change the plan, or is it a simple, frequent need?

Reach for it when: A subagent keeps needing results, checks or work that another subagent owns.

SituationRight mechanismWhy
Follow-up varies, depends on other helpers' results, or often changes the planReturn it to the coordinator as structured outputOnly the hub sees everything
Need is frequent, simple and uniform (for example 85% quick lookups: re-read a page, check a fact)Scoped cross-role tool for that one need; complex cases still go via the coordinatorSaves round trips without losing control
Subagents talk to each other directly, or want to share notes freelyRoute through the coordinator, not a shared storeDirect links and shared memory bypass routing and error handling
Subagent given another role's full toolsetRestrict tools to its roleAvoids over-provisioning
Independent tasks run one after anotherMultiple Task calls in one responseParallel spawning
A subagent fails, or reports only a generic errorStructured error back to the coordinator, saying what was triedThe hub owns recovery

Rule to remember: If a subagent's request depends on everyone's work or can change the plan, route it through the coordinator. Give a scoped cross-role tool only for frequent, simple, uniform needs.

Merged from 2 questions: Mock 6, scenario 3 question 2; Mock 5, scenario 3 question 9

1.3Subagent invocation and context passing

Mind map 8 of 83 · for

8Whether to hand work to a subagent at all

Ask yourself: Would delegating isolate verbose output or run independent work in parallel?

Reach for it when: You are tempted to spawn a subagent and want to know whether it is worth the hand-off cost.

SituationRight choiceWhy
Verbose discovery or long tool outputSubagent that returns a summaryKeeps the main context clean
Several independent tasksParallel subagents in one responseRun at the same time
Small, dependent steps reviewed as you goMain session, step by stepDelegation adds hand-off cost, buys nothing
Dependent task that is large and noisySequential subagent with earlier results in its promptIsolation pays; context passed explicitly
Long session filling up/compact or a scratchpadReclaim space without delegating

Rule to remember: Subagents earn their cost by isolating verbose output or running independent work in parallel. Without either, keep the work in the main session.

Merged from 1 question: Mock 4, scenario 4 question 7

Mind map 9 of 83 · for

9Where each piece of a subagent's context belongs

Ask yourself: Does this information change per run, and where must it be written so the subagent actually sees it?

Reach for it when: A subagent is missing facts, findings or rules, and you must decide between the Task prompt, the AgentDefinition and a tool.

What the subagent needsWhere it goesWhy
Material and decisions for this run (contracts, committee rules, scope)Written in full into the Task promptSubagents don't inherit the coordinator's history
Findings from earlier subagentsThe next subagent's Task prompt, completeNo shared memory between subagents
One fact another subagent producesCoordinator passes it in the promptNo automatic inheritance
Role, method, output format and quality bar that never changeAgentDefinition system promptWritten once, applies every time
Which tools it may useAgentDefinition tool restrictionsDoesn't change per run
Many quick or unpredictable lookups during its workScoped cross-role toolLeast privilege, fewer round trips via the coordinator
Complex work from another roleRoute via the coordinatorHub-and-spoke control
Source details for citations (source, page)Structured fields separate from contentKeeps attribution
Facts not in any sourceAsk or route to a personDon't infer; another agent's memory is not available
Two alternative directions from one baselinefork_sessionBranches a session; not a delivery channel

Rule to remember: Subagents inherit nothing. Per-run facts and prior findings ride in the Task prompt, fixed role rules live in the AgentDefinition, and a scoped tool is only for frequent lookups.

Merged from 4 questions: Mock 7, scenario 3 question 2; Mock 7, scenario 6 question 7; Mock 6, scenario 6 question 2; Mock 4, scenario 3 question 2

Mind map 10 of 83 · for

10Why a subagent's output is weak, generic or missing

Ask yourself: Which step of delegation failed: spawning, choosing the subagent, briefing it, or the inputs it was given?

Reach for it when: No subagent runs, the wrong one runs, or a subagent returns vague, generic or off-target work.

What you observeWhere the fault isFix
No subagent ever starts; coordinator does the work inlineCoordinator cannot spawnAdd "Task" to the coordinator's allowedTools
Wrong subagent, or none, starts for certain requestsSubagent descriptionsSharpen each AgentDefinition description
Generic or hedged answers; the facts are in the conversationContext not passedWrite the facts and goals into the Task prompt
Output wanders in scope or depthNo deliverable statedSay what to return and when it is complete: scope, dates, format, quality criteria
Vague output, and the task needs another helper's resultsSpawned before its input existedSequence it after that helper; pass results in full
Output ignores what you already know, or repeats earlier workPrior findings not handed onInclude complete prior findings in its prompt
Subagent needs backend records it cannot reachMissing toolsGive it scoped lookup tools
Understands the case but misapplies policyWeak instructionsImprove its system prompt in the AgentDefinition
Answers good but hard for the coordinator to useOutput formatAsk for a structured result
Subagent uses tools outside its roleOver-broad tool listRestrict tools in its AgentDefinition

Rule to remember: Brief a subagent as if it knows nothing: give it the facts and findings and say what done looks like. If no subagent ever runs, check that the coordinator can call Task before tuning descriptions or prompts.

Merged from 4 questions: Mock 7, scenario 1 question 2; Mock 6, scenario 3 question 3; Mock 5, scenario 3 question 1; Mock 5, scenario 4 question 6

Mind map 11 of 83 · for

11Speeding up a slow multi-agent run

Ask yourself: Is the time going on needless sequencing, unneeded subagents, or a real dependency?

Reach for it when: A multi-agent run takes too long.

SituationRight mechanismWhy
Independent subtasks run one after anotherSeveral Task calls in one responseThey run concurrently; time is the slowest, not the sum
One subtask needs another's resultsSequence that one after, pass the results in its prompt; keep the rest parallelIts input does not exist yet
Many requests don't need every subagentCoordinator selects subagents per request by complexitySkip stages that add nothing
Subagents fetch the same materialPartition scopeRemoves duplicate work
Large overnight job, no one waitingMessage Batches APIStops paying real-time prices
Subagent output is off-targetRicher explicit context in its promptSubagents know only their prompt

Rule to remember: Independent subtasks: emit all the Task calls in one response. Dependent subtasks: sequence them and pass the results. Skip subagents only when a request doesn't need them.

Merged from 2 questions: Mock 7, scenario 3 question 3; Mock 4, scenario 3 question 3

Mind map 12 of 83 · for

12How to brief a coordinator agent

Ask yourself: Do questions arrive in new shapes, or are they known, stable types?

Reach for it when: The coordinator's fixed procedure breaks on new questions, its output is inconsistent, or it accepts thin results from subagents.

What you observeWhere the fault isFix
Questions arrive in new shapes; the procedure breaksSteps fixed in advanceGoal plus quality criteria; the coordinator plans
Known, stable question types; output inconsistentInstructions alone are unevenAdd 2 to 4 worked examples
Steps are regular and predictable, for example one pass per fileTask is regularPrompt chaining: a fixed sequence
Coordinator accepts thin subagent returnsNo sufficiency standardState what counts as enough evidence
Broad topic, whole areas missingDecomposition too narrowBroaden the decomposition

Rule to remember: Brief a coordinator with the goal and the quality bar, and let it choose the steps.

Merged from 1 question: Mock 5, scenario 3 question 3

1.4Multi-step workflows, enforcement and hand-off

Mind map 13 of 83 · for

13Prompt or code for a rule that must hold

Ask yourself: What does one miss cost: is this a must-always rule or a should-usually one?

Reach for it when: A required step or limit is sometimes skipped and you must choose between instructions and enforcement.

RequirementRight mechanismWhy
Nice-to-have behaviour; misses acceptablePrompt instruction or criteria plus a few examplesCheap and good enough, but probabilistic
Tone, format, judgement or a quality bar varies between runsFew-shot examples; goals and quality criteria in the promptSteers judgement and consistency; still probabilistic
Step that must happen every time before an actionHook or prerequisite gate on the downstream toolPrompts have a non-zero failure rate
Hard limit on an action (for example a refund ceiling)PreToolUse hook that denies and redirectsDeterministic block at the side effect
Code computes a flag the agent readsPostToolUse hook on resultsStill relies on the agent
Model must call some tool instead of replyingtool_choice: "any"Guarantees a call
In Claude Code: allow or deny by tool, path or commandPermission rules in .claude/settings.jsonEnforced, declarative
In Claude Code: rule depends on the content of the call (amount, field, diff)PreToolUse hookEnforced, with code
In Claude Code: conventions, explore-before-change, or a personal preferenceCLAUDE.md; plan mode; .claude/settings.local.json or user settingsCLAUDE.md is guidance only; plan mode is a workflow; local settings apply only to you
Subtle errors in finished work, or a second view of an extractionIndependent review instanceFresh eyes after generation; not a human approval

Rule to remember: Code for must-always, prompt and examples for should-usually. Guidance such as CLAUDE.md is not enforcement: a prompt can raise the odds but can't guarantee the order.

Merged from 4 questions: Mock 7, scenario 1 question 3; Mock 7, scenario 3 question 4; Mock 5, scenario 6 question 7; Mock 4, scenario 4 question 8

Mind map 14 of 83 · for

14Which control enforces an order or forces a tool call

Ask yourself: Do you need to block a wrong call, force one call on one turn, or enforce an order across a whole session?

Reach for it when: A required step is skipped, a specific tool must run first, or the model answers in text instead of calling a tool.

RequirementMechanismCoverage and limit
Step must happen before a risky action every time, for each item, with many items per sessionPreToolUse hook or prerequisite gate on the risky downstream callEvery call; checks at the moment of action, keyed to the item
One specific tool must run first, once, on a single-item requestForced tool_choice (named tool) on the first turnThat request only; doesn't control later ordering
Model must call some tool instead of replying in texttool_choice: "any"That request; guarantees a call, not which or when
Block a call until a prerequisite ranHook or prerequisite gateStops wrong calls but can't force a call
Block an action above a threshold (for example a refund cap)Hook that blocks and redirectsEvery call; deterministic
Model picks the wrong tool among similar onesBetter tool descriptionsDescriptions drive selection, not enforcement; probabilistic
Preferred order, occasional slips acceptablePrompt instruction plus examplesProbabilistic
Tool output is messy or in mixed formatsPostToolUse hook to normaliseCleans results that already exist

Rule to remember: Hooks stop wrong calls; they don't cause right ones. Must-never rules need code on every call, keyed to the item; forced tool_choice shapes one request, not a whole session.

Merged from 3 questions: Mock 7, scenario 6 question 8; Mock 6, scenario 1 question 1; Mock 4, scenario 6 question 10

Mind map 15 of 83 · for

15Organising a request that raises several concerns

Ask yourself: Are the concerns lost in the first reply or many turns later, and how heavy is each one?

Reach for it when: A customer raises several issues in one message and some get missed or forgotten.

SituationRight mechanismWhy
Several small concerns, one or two calls eachExplicit list, work each, then endCheap, nothing missed
Several issues in one message; the first reply covers only oneSplit into concerns, investigate, answer togetherThe request was not decomposed
Concerns independent and slow to look upParallel tool calls with shared contextAvoids sequential investigation
Each concern is a long independent investigationParallel subagents, coordinator mergesIsolates heavy output
Concerns interact (one affects another)Handle together with shared contextNeed one view of the facts
Issues acknowledged, then forgotten many turns laterCase-facts block at the top of each promptFacts fade in a long context
Exact numbers blur after summarisationPersist transactional facts outside the summaryProgressive summarisation loses them
Agent ends early on a single concernStop on stop_reason, not text cuesText is a poor completion signal
One concern needs a policy exceptionEscalate that item, finish the othersPartial escalation is fine
Human picking up an escalation lacks contextStructured handoff summary (ID, root cause, amount, action)The handoff content was missing

Rule to remember: Decompose the request into a list and finish every item. If issues are lost in the first reply, fix decomposition; if they are lost many turns later, fix memory.

Merged from 2 questions: Mock 6, scenario 1 question 2; Mock 4, scenario 1 question 4

Mind map 16 of 83 · for

16Handing work over to a human or a later session

Ask yourself: Who picks the work up next, and what do they need to read first?

Reach for it when: Work is escalated to a person, a human's decision has to come back to the agent, or another session will continue the work.

SituationRight mechanismWhy
Human takes over without the transcript, or won't read itStructured handoff summary: ID, root cause, amount, what was tried, recommended action, open questionsMust stand alone so they can act at once
Human's time goes on what was tried and why it stoppedStructured summary first, transcript afterAnswers their real question; the transcript is backup
Human only struggles to find identifiersPin IDs at the topA smaller change is enough then
Queue needs routing onlyReason code plus summaryRouting alone loses detail
Long chat where recent turns matter mostStill summariseTruncation drops earlier steps
Human's decision comes back to the agentStructured resolution fields in the same record, loaded as case facts; if already structured in a system, give the agent a read toolFree-text shorthand is an unstructured return path
Deciding which items go to review, or a reviewer must re-verify valuesCalibrated field-level confidence; claim-to-source mappingRouting; provenance for everything
A later agent or Claude session continuesFresh session with a structured summary, or a scratchpad file of findingsAvoids stale context; survives context boundaries
Same person continues tomorrow in Claude Code--resume a named sessionKeeps the full history
Restart after a crashManifest or state fileStructured state persistence

Rule to remember: Handoffs go both ways. Hand a human a short structured summary of what was tried, what blocked it and what to do now, with the transcript only as backup; bring their decision back in structured fields the agent loads with its case facts.

Merged from 4 questions: Mock 6, scenario 4 question 7; Mock 6, scenario 6 question 3; Mock 5, scenario 1 question 8; Mock 4, scenario 1 question 10

Mind map 17 of 83 · for

17Fixing a gate that blocks a legitimate case

Ask yourself: Can the proof be seen in tool data, so the gate can learn a second kind of proof in code?

Reach for it when: A deterministic gate blocks a valid customer group or path.

SituationRight mechanismWhy
Gate blocks a valid customer group; proof exists in tool dataWiden the gate's condition in codeKeeps deterministic control
Same, but an occasional slip is acceptablePrompt steps plus examplesCheaper, but probabilistic
Proof needs something tools can't see (photo ID)Escalate with a structured handoffOnly a human can check
Agent skips verification on normal accountsPrerequisite gate (hook)Instructions have a non-zero failure rate
Refund above the limitHook blocks and redirects to escalationPolicy enforced in code

Rule to remember: Don't weaken a gate to fix its blind spot. Teach the gate a second kind of proof, in code.

Merged from 1 question: Mock 4, scenario 1 question 1

1.5Agent SDK hooks

Mind map 18 of 83 · for

18Hard stop, cleanup or nudge: which control acts at the right moment

Ask yourself: Must the rule hold every time, and does it act on the outgoing call or on the result?

Reach for it when: A policy keeps being broken and you must choose between a prompt, a PreToolUse hook and a PostToolUse hook.

GoalMechanismWhen it acts
Rule must hold every time (control failure, legal); the action must never happenPreToolUse hook or prerequisite gate intercepting the outgoing callBefore execution
Fewer wrong calls, judgement involvedExplicit criteria plus a few examples in the system promptProbabilistic; encourages good behaviour
Need to know afterwards what happenedPostToolUse hook or audit logAfter execution; monitoring, not prevention
Clean or normalise mixed-format resultsPostToolUse hookAfter execution
One tool must run before the othersGate, or forced tool_choice on that requestBefore the dependent call
Agent never needs the toolRemove it from allowedToolsTool never offered
Catch subtle errors in outputIndependent reviewAfter generation

Rule to remember: When a rule must hold every time, intercept the outgoing call in code before the action. Prompts improve behaviour; hooks guarantee it. PostToolUse is for results.

Merged from 2 questions: Mock 7, scenario 4 question 9; Mock 5, scenario 1 question 3

Mind map 19 of 83 · for

19Where to fix messy, sensitive or derived tool data

Ask yourself: Do you control the source, and is the job deterministic enough for code?

Reach for it when: The model gets numbers, dates or formats wrong, or sees fields it must never use.

SituationRight mechanismWhy
Messy formats from a server you run, or a field you own that isn't neededFix the server's response; stop returning the fieldFix at the source
Fixed formats (dates, codes, signs, decimals) from a server you don't controlPostToolUse hook normalises resultsExact parse; the model only ever sees one format
Model must never use a field; the server can't changePostToolUse hook masks itDeterministic, no server change
A yes/no fact derived from dataTool returns the computed fieldNo arithmetic left to the model
Value needs outside data (rates, prices)Tool against a dated sourceCorrect and traceable
Summed values may not matchcalculated_total alongside stated_totalSelf-check
Converter exists and its call is enforcedconvert_date tool behind a gateDeterministic only if the call can't be skipped
Formats vary unpredictably by layout, or occasional errors are tolerableFew-shot examples or prompt documentationCode can't list every case; cheap but probabilistic
Tool results bloated with irrelevant fieldsTrim results to the relevant fieldsToo much context
An action must be blocked (refund over limit)PreToolUse hook denies the outgoing callEnforcement, not formatting

Rule to remember: Fix data where you control it. Otherwise normalise or mask it in a PostToolUse hook before the model reads it, and compute derived facts in the tool; leave to the model only what code can't decide.

Merged from 4 questions: Mock 7, scenario 1 question 4; Mock 6, scenario 3 question 6; Mock 5, scenario 6 question 4; Mock 4, scenario 1 question 3

Mind map 20 of 83 · for

20When a hook exists but the policy still breaks

Ask yourself: What does the hook actually check, and does that match what the policy is about?

Reach for it when: A hook is in place, yet the limit is still broken or the agent keeps retrying rejected calls.

What you observeWhere the fault isFix
Limit broken by several small calls without any rejectionHook checks per call, but the policy is per totalHook sums the running total, blocks and escalates
Agent retries the same call after a rejectionError gives no category or retry signalStructured error: errorCategory, isRetryable: false
Hard rule written only in the promptPrompt compliance is probabilisticMove the rule into a hook
Borderline judgement about when to hand offUnclear decision boundaryExplicit criteria plus a few examples
One tool doing two different jobsTool designSplit into purpose-specific tools

Rule to remember: A hook enforces only what it checks. If the policy is about a total, the hook must check the total.

Merged from 1 question: Mock 6, scenario 1 question 4

1.6Task decomposition

Mind map 21 of 83 · for

21Fixed chain or adaptive decomposition for a multi-step job

Ask yourself: Can the steps be listed before the work starts, or does reading reveal new work?

Reach for it when: You are splitting a large job and must choose between a fixed pipeline and a plan that grows from findings.

SituationRight structureWhy
Same steps in the same order every time; must be auditableFixed prompt chain, one job per call, plus a joining passPredictable, replayable, each step checkable
Inputs present but out of orderFixed chain with sorting plus an integration passOrder is knowable up front
Next step depends on what is found: open-ended debugging where the cause could be anywhere, or reading reveals new work (missing documents to fetch)Adaptive decompositionSubtasks are generated from findings
Fixed list of items, many files or one long document; uneven depth and contradictionsPer-item or per-section passes plus an integration passAvoids attention dilution in one pass
Independent partsParallel subagentsSpeed; no dependencies
Drafts show coverage gapsRefinement loop: find gaps, re-delegate, re-synthesiseFills what the first pass missed
Discovery output is verbose or floods the main chatExplore subagentAvoids context pollution
Large code change with several valid designsPlan mode before editingChoose an approach before committing
Reviewer misses its own mistakes, or the same session reviews its own workIndependent review instanceNo shared reasoning; avoids self-review bias
Findings lost across long sessions or restartsScratchpad fileContext is volatile

Rule to remember: Use a fixed chain when the steps are known up front, one job per call; use adaptive decomposition when reading reveals new work. For a fixed list of items, give each its own pass, then one pass that compares them.

Merged from 5 questions: Mock 7, scenario 3 question 5; Mock 6, scenario 4 question 6; Mock 6, scenario 6 question 1; Mock 5, scenario 4 question 5; Mock 4, scenario 6 question 9

Mind map 22 of 83 · for

22Making agent runs faster or cheaper

Ask yourself: Does each request need the full pipeline, and is anyone waiting for the answer?

Reach for it when: Runs are too slow or too costly.

SituationRight mechanismWhy
Simple requests run the full pipelineCoordinator selects subagents by query complexityShort path for short questions
Cost matters and nobody waits for resultsMessage Batches API50% cheaper, up to 24 hours
Someone is waiting for the answerReal-time callsBatch has no latency guarantee
Independent subtasks run in seriesParallel Task callsTime becomes the slowest, not the sum
Loop needs a stopping rulestop_reason, not an arbitrary capCaps truncate good work

Rule to remember: When requests vary in complexity, let the coordinator choose which subagents each one needs. Use batch only when nobody is waiting.

Merged from 1 question: Mock 4, scenario 3 question 8

Mind map 23 of 83 · for

23Strategy for understanding unfamiliar code

Ask yourself: Do you need the answer to one specific question, or a broad map of a large area?

Reach for it when: You must make sense of code you don't know without wasting the context window.

GoalRight strategyWhy
Answer one specific question or bugGrep for entry points, then Read along the flowContext goes only to relevant code
Get a broad map of a large areaExplore subagent returns a summaryVerbose discovery stays out of the main context
Session long, context near full/compact or a scratchpad of key findingsKeeps what matters across boundaries
Answers start citing “typical patterns”Context degradation: narrow the scope and restart from findingsA degraded context gives generic answers
Need to design a change across many filesPlan mode (with Explore if discovery is heavy)Explore before committing

Rule to remember: For a specific question, Grep for the entry point and Read along the flow. Reading everything first wastes the context you need.

Merged from 1 question: Mock 4, scenario 4 question 5

Mind map 24 of 83 · for

24Splitting one growing prompt

Ask yourself: Is the problem where items sit in the prompt, or that one prompt can't fit every kind of input?

Reach for it when: One prompt serves many kinds of input and keeps growing, and items get missed or its guidance conflicts.

What you observeWhere the fault isFix
Long prompt, key items missed mid-wayPosition effectsKey items first, section headings
Guidance for one type contradicts anotherInstructions don't fit every inputClassify, then route to a focused prompt
Long documents, middle fields missedLost in the middleSegment the document
New layouts every weekPer-vendor notes don't scaleFew-shot examples of varied layouts
Output inconsistent under clear rulesUneven applicationFew-shot examples

Rule to remember: When one prompt serves several kinds of input and its parts conflict, classify first and route each input to a focused prompt.

Merged from 1 question: Mock 5, scenario 6 question 6

1.7Session state, resuming and forking

Mind map 25 of 83 · for

25Resume, fork or start fresh when continuing old work

Ask yourself: Is the earlier session still accurate, and do you want one line of work or two?

Reach for it when: You are coming back to earlier work and must choose between --resume, fork_session and a new session.

SituationRight mechanismWhy
Continue one line of work; nothing or little changed--resume (a named session)Full context, still accurate
Continue after one or two known files changed--resume, tell the agent what changed, re-read those filesRefreshes only the stale parts; keeps the design context
Much of the earlier tool output is stale; many files moved or refactoredNew session seeded with a structured summary, then re-fetchStale results mislead more than they help
Only the main findings matter for the next stepNew session with a structured summaryCompact; full detail not needed
Want two different approaches from the same valid baselinefork_sessionEach branch has the full baseline; neither sees the other
Want two approaches, but the baseline is stale or context nearly fullNew sessions seeded with a structured summaryAvoids stale results and overflow
Context getting full but still valid/compactFrees space; doesn't refresh files or remove stale facts
Long exploration needs to survive restartsScratchpad or manifest filePersists key findings outside the context
Exact amounts get lost in a long conversationCase-facts blockProtects transactional facts, not tool freshness
Large change with the approach undecided, or an independent side task with verbose outputPlan mode; or a subagent with explicit contextDesign before editing; isolates noise

Rule to remember: If little changed, resume and say what changed. If a lot changed, start fresh from a structured summary. To try two directions from a still-valid baseline, fork.

Merged from 6 questions: Mock 7, scenario 4 question 8; Mock 6, scenario 1 question 3; Mock 6, scenario 3 question 5; Mock 6, scenario 4 question 5; Mock 4, scenario 3 question 10; Mock 4, scenario 4 question 6

Back to the list

Domain 2: Tool design and MCP integration

2.1Tool descriptions and boundaries

Mind map 26 of 83 · for

26Claude picks the wrong tool: which lever to pull first

Ask yourself: Is the tool description the problem, or is something else steering the choice?

Reach for it when: Claude keeps calling the wrong tool, or keeps mixing up two similar tools.

What you observeWhere the fault isFix
Wrong tool picked across many phrasings, and the descriptions are one-linersThin or overlapping tool descriptionsRewrite the descriptions: purpose, inputs, an example, when to use it, when not to, and when to use the sibling tool instead
Descriptions are already good, but the misroutes always follow certain wordsWording in the system prompt (or in examples) that ties those words to a toolFind and rewrite that wording in terms of the customer's goal
Descriptions are detailed, but a few ambiguous edge cases still go wrongAmbiguous casesAdd 2 to 4 targeted, contrasting examples
Descriptions are good, but one tool does several different jobsTool designSplit or rename it into purpose-specific tools (after the description fix, not first)
Wrong pick, but the server is third-partyDescriptions you cannot editProject guidance in CLAUDE.md that steers the choice
The agent answers in text when it must call a toolTool choicetool_choice: "any" or a forced tool
A call must never happen without a condition, or tools must run in a fixed orderInstructions cannot guarantee itA hook or prerequisite gate in code, or a forced tool_choice
Too many tools on one agentTool distributionGive each agent the 4 to 5 tools its role needs
Results need cleaning before the model sees themRaw tool outputPostToolUse hook

Rule to remember: Descriptions are the main way Claude picks a tool, but not the only one. If you own the tool, fix a vague description first (when to use, when not to, inputs); if the descriptions are already good and misroutes follow certain words, look for those words in the system prompt.

Merged from 5 questions: Mock 6, scenario 1 question 5; Mock 6, scenario 3 question 7; Mock 6, scenario 4 question 4; Mock 5, scenario 1 question 2; Mock 4, scenario 1 question 8

Mind map 27 of 83 · for

27A tool is called with bad inputs: description, examples or a split

Ask yourself: What was the model actually told about this tool and its inputs?

Reach for it when: The right tool is called, but with wrong inputs or a misused catch-all parameter.

What you observeWhere the fault isFix
Wrong inputs, and the description is one lineDescriptionAdd the input format, examples, edge cases and boundaries
The description is full, but behaviour is still inconsistentNeeds demonstrationA few targeted examples
Good description, but a catch-all parameter is still misused, or one generic tool does several jobsTool designSplit into purpose-specific tools with typed inputs
Two tools have overlapping descriptionsBoundariesState when to use each
Bad input reaches the tool, it fails vaguely, and the agent can't recoverError responseStructured validation error: category, retryable, message
A valid empty result is confused with a failureError meaningDistinguish an access failure from "no results"
Results arrive in mixed formatsResult shapePostToolUse hook to normalise

Rule to remember: A minimal description leads to bad calls, so first add input format, examples, edge cases and boundaries. When a good description still does not stop misuse of a catch-all input, split the tool into purpose-specific tools with defined inputs.

Merged from 2 questions: Mock 7, scenario 1 question 6; Mock 5, scenario 1 question 10

2.2Structured tool errors

Mind map 28 of 83 · for

28What error to return for each kind of tool failure

Ask yourself: What does the agent need to know about this failure to recover from it?

Reach for it when: A tool fails and the agent retries hopeless calls, gives up on recoverable ones, or can't explain what happened.

Kind of failureWhat to returnWhat the agent does next
Transient: a timeout or brief outage that passes on a retryRetry with backoff inside the tool first; if it still fails, isError with a transient category, retryable trueRetries, or tells the customer to wait
Business rule or policy says no (over the refund limit, past the cut-off, card closed)isError, business category, isRetryable: false, and a customer-friendly reasonStops, explains, and offers the next option
Validation: bad input such as a wrong ID formatValidation category, saying what was wrong and the expected formatFixes the input and retries
Not allowed for this userPermission categoryEscalates or explains
The lookup worked but found nothingSuccess with an empty result, not an errorReports that nothing was found
Every failure says "Operation failed", or two failure kinds return the same messageerrorCategory + isRetryable + a short descriptionCan choose the right response instead of guessing
Raw error codes arrive in mixed formatsNormalise them in a PostToolUse hookReads one consistent shape
A rule the agent can check in advancePut it in the tool descriptionAvoids the failing call altogether
A subagent can't recover locallyPass the error up with partial resultsThe coordinator decides

Rule to remember: Return the error's category and whether a retry can help; a uniform "failed" leaves the agent guessing. If two failures need different responses, they need different categories, and a business-rule failure should be marked not retryable with a sentence the agent can tell the customer.

Merged from 4 questions: Mock 7, scenario 1 question 7; Mock 7, scenario 4 question 2; Mock 6, scenario 1 question 6; Mock 4, scenario 1 question 2

Mind map 29 of 83 · for

29Telling "found nothing" apart from "could not look"

Ask yourself: Did the tool look and find nothing, or could it not look at all?

Reach for it when: A search or lookup returns nothing, and an outage might be hiding behind the empty answer.

SituationRight responseWhy
Genuinely nothing foundA valid empty result ([])It is a real answer
The store is unreachable for minutes or longer, so an outage looks like 'no results'isError with a category, transient and retryableThe caller can hold or retry later instead of trusting a false "nothing there"
Brief, intermittent blips of a few secondsRetry locally with backoff, then return an errorRecovers without bothering the caller
Bad input from the callerValidation error, not retryableRetrying won't help
Policy forbids the actionBusiness error, not retryable, with an explanationIt needs a different path
Every failure says 'Operation failed'Structured categories: transient, validation, business, permissionThe caller can tell failures apart
A subagent fails and the whole run stopsReturn partial results and error context to the coordinatorAvoids stopping everything for one failure
Claims lose their sourcesCarry claim-source metadata through synthesisKeeps provenance

Rule to remember: Never let 'could not look' share a return value with 'looked and found nothing'. Return a structured, retryable error for outages and keep the empty result for a real no-match.

Merged from 2 questions: Mock 6, scenario 3 question 8; Mock 4, scenario 6 question 8

Mind map 30 of 83 · for

30What a failing subagent sends back to the coordinator

Ask yourself: Can this failure be fixed locally, and if not, what does the coordinator need in order to decide?

Reach for it when: A subagent's tool call failed and you must decide what to retry and what to report upward.

What happenedLocal actionWhat to return
Transient fault (timeout, 503)Retry with backoffIf it still fails: a structured error plus partial results
Permission or access deniedDon't retryCategory, affected items, partial results and alternatives
Bad input (validation)Fix the input and retryOnly if it can't be fixed: the validation detail
The search succeeded and found nothingNothing to recoverA valid empty result, clearly not an error
Any failureNever hide it or substitute something silentlyA generic 'failed' and a fake success both block recovery

Rule to remember: Retry only what can recover. Otherwise return structured error context with partial results and alternatives, and let the coordinator decide.

Merged from 1 question: Mock 4, scenario 3 question 7

2.3Tool distribution and tool_choice

Mind map 31 of 83 · for

31Which tool_choice setting to use

Ask yourself: What may Claude still choose: text or a tool, which tool, or nothing at all?

Reach for it when: Claude replies in text when a tool call is needed, or a required first step sometimes doesn't run.

What you needSettingWhy
Text or a tool call; the model decides freely"auto"The default; it may return text
Some tool call instead of plain text; several tools are valid and Claude chooses well"any"Bans text but keeps the choice of tool
One specific tool must run first, every timeForced {"type":"tool","name":…} on that first request, then back to autoRemoves the choice too; guaranteed
Structured output from one schemaA forced extraction toolSchema-compliant output
The tool input must match the schemaStrict schemaControls the shape, not whether a call happens
Certain tools only after a prerequisite has returnedA hook or prerequisite gate in codeGuaranteed across turns, in code
An instruction to call a tool firstPrompt guidanceProbabilistic: fine as guidance, not as a guarantee
Claude calls the wrong tool, or confuses two similar tools at randomNot a tool_choice problem: expand the descriptions with inputs, examples and boundariesIt is a selection problem; descriptions help picking but can't promise order
Recover after a bad callA structured isError resultRecovery, not prevention
Results arrive in mixed formatsA PostToolUse hook to normaliseDifferent sources, one shape

Rule to remember: "any" guarantees some tool call, not which one. To make one exact tool run first, force it by name on that request; descriptions improve picking but cannot promise order.

Merged from 5 questions: Mock 7, scenario 1 question 5; Mock 7, scenario 3 question 7; Mock 7, scenario 4 question 4; Mock 5, scenario 1 question 7; Mock 5, scenario 6 question 5

Mind map 32 of 83 · for

32Too many tools, or the wrong tools, on one agent

Ask yourself: Is the agent confused among the right tools, or holding tools it shouldn't have?

Reach for it when: Tool selection gets worse as tools are added, or an agent keeps using tools outside its role.

What you observeWhere the fault isFix
Misroutes spread evenly and started as the tool count grewToo many tools on one agentKeep the frequent tools on the front-line agent and move rare tools to a specialist
Many off-role tools, and the descriptions are already goodTool distributionScope the AgentDefinition's tool list to the role
Misroutes cluster between look-alike pairs, or a few tools with one-line descriptions get confusedOverlapping or thin descriptionsExpand the descriptions: inputs, examples, boundaries
A rare tool is called when it shouldn't beMissing controlA hook to block it, if it must stay
A subagent often needs one quick lookup from another roleStrict scoping is too tightOne limited cross-role tool
A generic tool does many jobsTool designSplit into purpose-specific tools
Many exploratory calls just to learn what existsNo catalogueAn MCP resource

Rule to remember: Too many tools on one agent degrades selection. Descriptions fix confused picks among the right tools; scoping fixes an agent holding the wrong tools.

Merged from 2 questions: Mock 7, scenario 3 question 8; Mock 4, scenario 1 question 7

Mind map 33 of 83 · for

33A subagent needs help from outside its role

Ask yourself: What kind of outside help is it: a frequent simple check, or rare open-ended work?

Reach for it when: A subagent keeps reaching for capabilities that belong to another role in the middle of a task.

SituationRight mechanismWhy
Frequent, simple, uniform lookups, such as quick checks of one factA narrow cross-role tool such as verify_factRemoves round trips without giving broad access
The needed facts are known before the subagent startsPass them explicitly in its promptNo tool or round trip needed
Rare, complex questions needing several sourcesRoute them via the coordinatorIt can delegate and sees all the results
The next step depends on other subagents' findingsThe coordinator decidesOnly it sees everything
Open-ended research mid-task, because off-role tools are availableRemove them from the AgentDefinition; the subagent reports gapsOff-role tools get used and misused
Too many tools, and it picks the wrong oneCut to the 4 to 5 tools the role needsTool overload
Material it retrieved itself lacks sourcesClaim-source mapping, if retrieval is in its roleProvenance
It ignores a written ruleMake the boundary structuralPrompts are probabilistic

Rule to remember: Scope tools to the role and route real gaps back through the coordinator, then add one narrow cross-role tool for the frequent, simple need. Complex cases stay with the coordinator.

Merged from 2 questions: Mock 5, scenario 3 question 6; Mock 4, scenario 3 question 4

Mind map 34 of 83 · for

34Controlling a risky tool: remove it, gate it, or guide it

Ask yourself: Is this action forbidden, allowed with approval, allowed under a limit, or just a preference?

Reach for it when: An agent has a tool that could do harm, and you must decide how hard to control it.

What you observeWhere the fault isFix
The action is not allowed from the agent at allAccessDeny or remove the tool; keep the rest
The action is allowed with human approvalGateA PreToolUse hook that asks or blocks
The action is allowed under a threshold, such as an amountBusiness ruleA hook that blocks above it and redirects
A preference, not a hard ruleGuidanceA CLAUDE.md or prompt instruction
The agent misuses tools outside its roleTool distributionScope tools per role

Rule to remember: Not allowed from the agent: remove the tool. Allowed with approval: a hook. A preference: an instruction.

Merged from 1 question: Mock 5, scenario 4 question 8

2.4MCP servers in Claude Code and agents

Mind map 35 of 83 · for

35Reuse a community MCP server, describe conventions, or build your own

Ask yourself: Does something already exist for this system, and is the gap capability or just context?

Reach for it when: You need to connect Claude to an outside system and must decide what to use or build.

SituationRight choiceWhy
A standard system with maintained community serversUse a community MCP serverAlready built and maintained
Team-specific fields and conventionsDescribe them in CLAUDE.mdConventions are context, not capability
A proprietary system with no equivalentBuild a custom MCP serverNothing to reuse
The agent must change things (comment, transition)MCP toolsActions need tools
The agent must browse a catalogueMCP resourcesContent to read

Rule to remember: Prefer community MCP servers for standard integrations, put team conventions in CLAUDE.md, and build a custom server only when nothing exists.

Merged from 1 question: Mock 4, scenario 4 question 10

Mind map 36 of 83 · for

36Where an MCP server's configuration lives

Ask yourself: Who needs this server, and how do they get it without a secret being committed?

Reach for it when: You are adding an MCP server and must choose between the project file and your user file.

SituationWhere it goesWhy
The whole team (and CI) needs it from first cloneProject .mcp.json, committedVersion control shares it with every clone
The shared server needs a secret${VAR} expansion in .mcp.json; each person sets the variable in their environmentThe file is committed; the value is not
A token written into a committed fileNowhereUse expansion instead
One person, a personal or experimental serverUser-level ~/.claude.jsonPrivate, not in git, and keeps trials out of everyone's tool list
One person, across many repositoriesUser-level ~/.claude.jsonConfigured once for all repositories
Only one machine (such as the CI runner) uses itUser-level ~/.claude.json, secret injected at runtimePersonal scope is enough; nothing to share
An audit needs per-person actionsPer-person tokens, not a shared oneIdentity
Instructions on how to use a serverCLAUDE.mdNot configuration; no servers are registered there
A standard integration such as JiraA community MCP serverDon't build what already exists
The agent prefers Grep over a better MCP toolImprove the MCP tool's descriptionSelection follows descriptions

Rule to remember: Shared servers go in the project's committed .mcp.json with secrets as ${VAR}, never as values; personal or experimental servers go in ~/.claude.json.

Merged from 4 questions: Mock 6, scenario 4 question 2; Mock 6, scenario 5 question 1; Mock 5, scenario 4 question 2; Mock 4, scenario 4 question 3

Mind map 37 of 83 · for

37A better MCP tool is ignored or missing

Ask yourself: Is the MCP tool missing from Claude's list, or listed but losing to a built-in?

Reach for it when: Claude uses a built-in such as Grep, or says it has no such tool, when a better MCP tool should be doing the job.

What you observeWhere the fault isFix
Claude says it has no such tool; the server was added mid-sessionNot yet discoveredRestart so it connects
The tools are listed, but Claude picks a built-in; the MCP description is thin or vagueThe description doesn't distinguish the toolRewrite it: capabilities, inputs, sample queries, and when to prefer it over the built-in
The description is already full, and the built-in is still chosenContext elsewhereAdd a project instruction
You can't edit a third-party tool's descriptionDescription out of reachGuidance in CLAUDE.md
The competing tool has no legitimate use for this agentTool distributionRemove it from the agent's tools
A tool must never be used herePermissionsDeny it in settings
Several similar tools are confused with each otherGeneric, overlapping toolsClarify boundaries, or rename and split into purpose-specific tools
Misroutes follow specific words in requestsSystem-prompt wordingRewrite that wording
The agent probes to learn what existsNo catalogueAn MCP resource
The server fails for one person onlyTheir environment or tokenCheck the exported variable

Rule to remember: A tool missing after a mid-session config change means reconnect; a tool present but ignored means fix its description first, saying what it does that the built-in can't, before removing the alternatives.

Merged from 4 questions: Mock 7, scenario 5 question 5; Mock 5, scenario 3 question 10; Mock 5, scenario 4 question 3; Mock 4, scenario 4 question 4

Mind map 38 of 83 · for

38Too many exploratory calls: what the agent is missing

Ask yourself: Is the agent calling tools to find out what exists, or because a tool is unclear?

Reach for it when: The agent makes many tool calls, probing around before it does any real work.

What you observeWhat's missingFix
Exploratory calls to learn what exists: a catalogue, hierarchy or schemaA content catalogueExpose it as an MCP resource: readable content the server keeps current
The structure is small and rarely changesA one-time statement of itDescribe it in the system prompt
The agent must find specific items by queryA search tool with a clear descriptionThat is an action, so it needs a tool
Calls are badly formed or irrelevant, or the wrong tool is picked among similar onesA clear descriptionExpand the description: inputs, examples, edge cases, boundaries
One generic tool does several jobsPurpose-specific toolsSplit and rename
Each call returns huge payloads that fill the contextTrimmed resultsTrim to the relevant fields in a PostToolUse hook
Verbose discovery floods the main conversationIsolationAn Explore subagent that returns a summary
Built-in Grep is preferred over a better MCP toolA strong MCP tool descriptionSay what the MCP tool does better

Rule to remember: If an agent spends tool calls learning what exists, publish that as an MCP resource: resources show content, tools act or fetch. Badly formed calls and wrong picks mean fixing descriptions.

Merged from 4 questions: Mock 7, scenario 5 question 4; Mock 6, scenario 1 question 7; Mock 6, scenario 4 question 3; Mock 4, scenario 3 question 9

2.5Built-in tools (Read, Write, Edit, Bash, Grep, Glob)

Mind map 39 of 83 · for

39Which built-in tool to find and explore code

Ask yourself: Are you matching names, searching contents, reading a file, or only after a conclusion?

Reach for it when: You need to locate files or understand code and must pick between Glob, Grep, Read and an Explore subagent.

What you needTool or approachWhy, or what to watch out for
Files whose names or paths match a pattern (for example all tests)GlobMatches paths only, never contents; fast when naming is consistent
Every file that contains a text or nameGrepSearches contents, so it works when names are unreliable; only as good as the text marker
What a file saysReadRead selectively, not everything
Who calls a function, or how a value flows from an entry point, when you will fix it hereGrep for the entry point or references, then Read along the calls and importsIncremental, one file at a time, not read-all-upfront
A broad survey where only the conclusion is wanted, or context is tightAn Explore subagentReturns a summary and keeps noise out of the main context
A long session losing earlier findingsA scratchpad file of key findingsContext degrades over time
Change one unique snippetEditA targeted change by unique match

Rule to remember: Glob matches file names and paths; Grep searches inside files. Start from the entry point and Read outward, and delegate to Explore only when you want the conclusion, not the trail.

Merged from 4 questions: Mock 7, scenario 4 question 1; Mock 6, scenario 4 question 1; Mock 5, scenario 4 question 1; Mock 4, scenario 4 question 1

Mind map 40 of 83 · for

40Changing a file: Edit, replace_all, or Read and Write

Ask yourself: Is the text you want to change unique in the file?

Reach for it when: You need to change a file, or an Edit just failed.

SituationToolWhy
Small change, and the text is unique in the fileEditTargeted change; the rest is untouched
Match not unique, but neighbouring lines differEdit with old_string widened by nearby linesThe anchor was too short
Match not unique, and the copies are identical for many lines everywhereRead the file, then Write it back changedNo unique anchor exists, so Edit can't target it
Every occurrence should changeEdit with replace_allThe intent is all copies
Text not found at allRe-read the file, then editThe file changed since it was read
A brand-new file, or a full rewriteWriteWrite replaces the whole file
You don't know where the text isGrep for content, then ReadThat is locating, not editing
The change belongs in the source of generated codeEdit the generator, if every output should changeYou were in the wrong file

Rule to remember: Edit needs a unique text match. If the match is ambiguous, widen it to something unique; only when nothing is unique, Read the file and Write it back.

Merged from 4 questions: Mock 7, scenario 4 question 3; Mock 6, scenario 5 question 2; Mock 5, scenario 4 question 4; Mock 4, scenario 4 question 2

Back to the list

Domain 3: Claude Code configuration and workflows

3.1CLAUDE.md hierarchy and scope

Mind map 41 of 83 · for

41Where a convention or instruction should live in the CLAUDE.md hierarchy

Ask yourself: Who needs this guidance, who owns it, and which files does it follow?

Reach for it when: You have a new standard, convention or preference and must decide which memory file or folder to put it in.

SituationRight homeWhy
Standard for every file, shared with the team and CIRoot or project CLAUDE.md (committed)Always loaded in every session, shared via the repo
Standard owned and edited elsewhere in the repo, applies everywhere@import from CLAUDE.mdReferences the live file, no copy to drift
Convention that follows a file type across folders.claude/rules/ with a paths: globLoads only when matching files are touched
Convention that belongs to one folder onlyThat directory's CLAUDE.mdLoads only when working there
A multi-step procedure people run on requestSkill (.claude/skills/) or commandLoaded only when invoked, not always on
Personal preference for one developer~/.claude/CLAUDE.mdUser-level, not shared via version control

Rule to remember: Ask who needs it and which files it follows. Team-wide standards go in the committed project CLAUDE.md, conventions that follow a file pattern across folders go in .claude/rules/ with paths:, and a document someone else owns is referenced with @import, not copied.

Merged from 3 questions: Mock 7, scenario 5 question 1; Mock 6, scenario 2 question 1; Mock 4, scenario 2 question 1

Mind map 42 of 83 · for

42Instructions ignored or missing for some people: diagnosing which memory file is at fault

Ask yourself: Is the guidance actually loaded, and if so, which file is it coming from?

Reach for it when: Claude ignores a rule, or follows it for one person but not for teammates or CI.

What you observeWhere the fault isFix
Not sure which memory files are activeUnknown loadingRun /memory to list the files actually in context
Rules work locally but not for teammatesConventions only in someone's ~/.claude/CLAUDE.md; user level does not travel with the repoMove them into the project CLAUDE.md
Unwanted habit traced to one person's fileUser-level source, or a personal file contradicting the projectRemove or adjust that personal instruction
Unwanted habit from many people, no single sourceMissing team standardAdd a project rule
File missing from /memoryBroken @import path or wrong scopeFix the path or move the file
Rule file with paths: never loadsThe glob doesn't match real filesFix the glob
Conventions span many folders by file type, or apply only to some filesDirectory-bound or too-broad placement.claude/rules/ with paths:
File is loaded, but output follows the rules looselyInstructions alone are inconsistentAdd 2–4 few-shot examples
CLAUDE.md is huge and hard to maintainMonolithic memorySplit it with @import
Context is fullContext size, not memory/compact reduces usage; it is not a memory check

Rule to remember: Before you change any file or tune a prompt, run /memory to confirm the guidance is loaded. Then fix the habit at the file it comes from: home-folder CLAUDE.md is personal, team conventions go in the committed project CLAUDE.md.

Merged from 5 questions: Mock 7, scenario 2 question 5; Mock 7, scenario 5 question 2; Mock 6, scenario 4 question 9; Mock 5, scenario 2 question 2; Mock 4, scenario 2 question 6

3.2Slash commands and skills

Mind map 43 of 83 · for

43Sharing a command with the team versus keeping it personal

Ask yourself: Who needs the command, and how will it reach them?

Reach for it when: A slash command or setting works for you but you must decide whether teammates get it on clone.

Who needs itRight homeWhy
Everyone who clones this repo.claude/commands/ in that repoShips with the code, shared via git
Several reposCommit it to each repoEach clone carries its own copy
Only me, every repo, or my own variant~/.claude/commands/ (different name for a variant)Personal, not shared
Everyone, and every machine is set up centrallyUser-level copy via onboardingWorks only with that setup
Always-on team standard, not a commandProject CLAUDE.mdLoaded every session, shared
Always-on personal preference~/.claude/CLAUDE.mdNot shared
Shared MCP server.mcp.jsonShared via the repo

Rule to remember: Shared commands go in each repository's .claude/commands/; personal ones go in ~/.claude/commands/. Only what is committed arrives on clone.

Merged from 2 questions: Mock 7, scenario 2 question 1; Mock 4, scenario 2 question 5

Mind map 44 of 83 · for

44Command, skill, path rule or CLAUDE.md: choosing the home by when content should load

Ask yourself: Should this load always, when certain files are edited, or only when someone asks?

Reach for it when: You are packaging a procedure, standard or convention and must pick between a command, a skill, a rule file and CLAUDE.md.

SituationRight homeWhen it loads
Standards every session needsProject CLAUDE.md (optionally with @import)Always loaded
Conventions for certain file types.claude/rules/ with paths:When a matching file is edited
Shared prompt template or routine, small outputProject command in .claude/commands/On request; versioned and runs in the session
Shared multi-step workflow with verbose or huge working outputProject skill with context: forkWhen invoked; runs isolated and returns only the result
On-demand workflow that needs tool limitsSkill with allowed-toolsWhen invoked, with restricted tools
Personal routine or experiment~/.claude/commands/ or ~/.claude/skills/On request, for one engineer only
Personal preference~/.claude/CLAUDE.mdAlways, for one user only

Rule to remember: Choose the home by when it should load: always (CLAUDE.md), by path (rules with paths:), or on request (commands and skills). Shared heavy-reading routines run in a project skill with context: fork.

Merged from 7 questions: Mock 7, scenario 2 question 4; Mock 7, scenario 4 question 7; Mock 6, scenario 2 question 5; Mock 6, scenario 4 question 8; Mock 6, scenario 5 question 4; Mock 5, scenario 5 question 7; Mock 4, scenario 2 question 2

Mind map 45 of 83 · for

45Controlling a skill: forked context, allowed tools and arguments

Ask yourself: Is the problem what the skill can do, how much it puts into my context, or what input it needs?

Reach for it when: A skill floods the conversation, does something it shouldn't, or needs a value from the user.

What you observeWhere the fault isFix
One skill reads a lot, reports a little; only the summary mattersVerbose step in the main contextcontext: fork in the skill
Shared on-demand workflow whose detail is needed afterwardsMust run inline.claude/commands/ with argument-hint and allowed-tools
Skill must not use certain tools (for example must not edit files), wherever it runsCapability of the skillallowed-tools in SKILL.md frontmatter
Instruction in the skill body is ignoredBody instructions are probabilisticTurn it into a capability limit with allowed-tools
Block applies to one project, whoever calls the toolProject policyPreToolUse hook in project settings
Skill needs a parameter from the userInvocationargument-hint
Ad-hoc exploration in the middle of a taskVerbose discoveryExplore subagent that returns a summary
Session has grown long over hoursAccumulated history/compact, or a scratchpad plus a fresh session

Rule to remember: Fork a skill with context: fork when only its summary matters, and keep it inline when the user will build on its detail. To make a skill unable to do something, restrict allowed-tools in its frontmatter; the limit travels with the skill.

Merged from 3 questions: Mock 5, scenario 2 question 3; Mock 5, scenario 2 question 4; Mock 5, scenario 4 question 10

3.3Path-specific rules

Mind map 46 of 83 · for

46Path-scoped rules versus directory CLAUDE.md for file conventions

Ask yourself: How are the files this convention covers grouped: by pattern across folders, or inside one folder?

Reach for it when: A convention applies only to some files and you must choose between a .claude/rules/ file and a folder's CLAUDE.md, or a path rule never applies.

Convention applies toRight homeLoads when
A file type spread across several folders.claude/rules/ file with a paths: globEditing a matching file, wherever it sits
Everything inside one directoryThat directory's CLAUDE.mdWorking in that directory
The whole project, every taskRoot CLAUDE.md (optionally with @import)Every session
A task someone runs on requestSkill or slash commandWhen invoked
One engineer's personal preference~/.claude/CLAUDE.mdAlways, not shared
Root file too long to maintain@import modulesOrganises it, but still always loads
A path rule never appliesThe glob matches no real filesFix the glob; check with a matching file and /memory

Rule to remember: Conventions for a file pattern across folders go in .claude/rules/ with a paths: glob; one folder's conventions go in that folder's CLAUDE.md. A path rule that never loads usually has a glob that matches nothing.

Merged from 5 questions: Mock 7, scenario 2 question 2; Mock 7, scenario 4 question 6; Mock 6, scenario 2 question 2; Mock 6, scenario 5 question 3; Mock 5, scenario 2 question 1

3.4Plan mode or direct execution

Mind map 47 of 83 · for

47Plan mode, Explore subagent or direct execution for a change

Ask yourself: What is still undecided about this change, and how wide is it?

Reach for it when: You are about to start a code change and must decide whether to plan first, explore first or just edit.

SituationRight approachWhy
Small, single-file, fully specified changeDirect execution, then review the diffNothing left to decide
Small edit in a big fileEdit on a unique match, not a full rewriteLimits the blast radius
Many files, several valid designs or unknown dependenciesPlan modeExplore and decide before editing
Many files, approach settled, good testsDirect execution in increments with testsTests catch slips; nothing left to design
Need to map unfamiliar code without flooding context, no decision yetExplore subagentIsolates discovery and returns a summary
Several valid designs and noisy discoveryPlan mode plus an Explore subagentDesign first; noise kept out
Design settled, location unknownExplore subagent, then direct executionOnly discovery is hard
Requirements unclear to the engineerInterview pattern: Claude asks firstSurfaces what the person knows
Behaviour well defined, regressions likelyTests first, then iterateObjective feedback on each change
Settled conversion repeated many timesSkill or commandReusable on-demand workflow

Rule to remember: Many files plus more than one valid design means plan mode before any edits; a small, clear change goes direct with a diff review. An Explore subagent understands code but does not decide, and tests protect a chosen design but don't choose it.

Merged from 7 questions: Mock 7, scenario 2 question 3; Mock 7, scenario 4 question 5; Mock 6, scenario 2 question 3; Mock 6, scenario 2 question 6; Mock 5, scenario 4 question 9; Mock 4, scenario 2 question 3; Mock 4, scenario 4 question 9

3.5Iterative refinement

Mind map 48 of 83 · for

48Examples, tests or interview: telling Claude what correct means

Ask yourself: What do you already know about the right answer, and what kind of feedback is missing?

Reach for it when: Iteration keeps going wrong: Claude misreads the task, fixes break other cases, or new cases surprise you every run.

What you observeWhat is missingFix
Requirements unclear or domain unfamiliar; new, unforeseen cases appear each runRequirements unknown to the authorInterview pattern: Claude asks questions first
You know the trustworthy outputs, but prose keeps being misreadAmbiguous prose descriptionConcrete input/output examples in the prompt
Fixes break different earlier cases each round, caught by handNo automatic check of all casesWrite tests first and run them after every edit
Runnable tests already capture the behaviourNothing; use themTest-driven iteration against those tests
Two specific problems keep breaking each otherInteracting problems sent separatelySend them together in one message
Independent small fixesUnrelated problems bundledSend them one after another
Large or multi-file change with several valid designsArchitecture, not feedbackPlan mode

Rule to remember: When the requirements are unclear, have Claude interview you before it writes code. Once the right answers are known, iterate against runnable tests if they exist, and use pasted input/output examples only when there are none.

Merged from 5 questions: Mock 6, scenario 2 question 4; Mock 6, scenario 4 question 10; Mock 6, scenario 5 question 5; Mock 5, scenario 2 question 5; Mock 4, scenario 2 question 4

Mind map 49 of 83 · for

49One message or several when you have multiple problems

Ask yourself: Does the fix for one problem depend on the outcome of another?

Reach for it when: You have several issues to raise with Claude and must decide whether to send them together or one at a time.

What you observeWhere the fault isFix
Problems whose fixes depend on each otherInteractionOne message
Independent problemsNo interactionSeparate messages, in sequence
Related by topic, but nothing depends on the outcomeLooks linked, isn'tSeparate messages
Everything ships in one pull requestDelivery groupingSays nothing about how to prompt
Large multi-file change with design choicesArchitecturePlan mode first

Rule to remember: Send interacting problems in one message and independent ones separately. Group by dependency, not by topic or pull request.

Merged from 1 question: Mock 5, scenario 2 question 6

3.6Claude Code in CI/CD

Mind map 50 of 83 · for

50A CI step that hangs, ends empty or behaves differently from local

Ask yourself: Which part of the invocation is wrong: mode, permissions, output shape or configuration scope?

Reach for it when: A Claude Code step in CI hangs, finishes with nothing, or gives different results than on a laptop.

What you observeWhere the fault isFix
Job hangs until the job limit, waiting for inputSession is interactiveRun with -p / --print
Ends fast, empty, no error, right after a tool requestTool not permitted, nobody to approveAllow the needed tools for the CI run
Step finishes, but prose is hard to parseUnconstrained output shape--output-format json + --json-schema
Review ignores repo conventions, or flags differ from localMissing project context; criteria only in personal ~/.claude/CLAUDE.mdCommitted project CLAUDE.md
MCP tools missing in CI onlyServer set in user configProject .mcp.json
Review misses flaws in code it just wroteSame-session self-reviewSeparate, independent invocation
Step needs no tool loop and can wait hoursInterface choiceMessage Batches API

Rule to remember: A step that hangs is an invocation problem, so use -p first. Non-interactive runs cannot approve anything, so fast, empty, error-free output right after a tool request means the tool wasn't allowed.

Merged from 2 questions: Mock 5, scenario 5 question 4; Mock 4, scenario 5 question 1

Mind map 51 of 83 · for

51Getting output in the shape its reader needs: schema, forced tool or format examples

Ask yourself: Who reads the output, a program or a person, and through which interface?

Reach for it when: Claude's output is hard to use downstream: a script can't parse it, the layout varies, or a value is wrong.

SituationRight mechanismWhy
Run without waiting for input-p / --printNon-interactive mode
A script reads findings from claude -p--output-format json + --json-schemaValid JSON in your named fields, set at generation
Your own app calls the Messages API and must always get one shapeTool with a JSON schema, forced via tool_choiceThe turn must be that tool call
Findings posted as PR commentsJSON + schema, then the script postsStructured findings
People read it; layout and detail vary2–4 few-shot examples of the formatConsistency, not a contract
Output parses but a value is wrong, and time is availableValidate in code, retry with the specific errors appendedSchemas stop syntax errors, not semantic ones
Value absent from the sourceNullable field, route to a personRetries can't find what isn't there
Need loud failure when a contract changesContract testDetects, doesn't prevent
Large PR, uneven depthPer-file passes + an integration passAttention dilution

Rule to remember: Prose is for people; schemas are for programs. --output-format json gives valid JSON and --json-schema gives your JSON, so constrain at generation when a consumer has a fixed contract.

Merged from 4 questions: Mock 7, scenario 2 question 6; Mock 7, scenario 5 question 3; Mock 5, scenario 5 question 3; Mock 4, scenario 5 question 2

Mind map 52 of 83 · for

52Where CI-specific instructions live versus repo-wide ones

Ask yourself: Who needs these instructions: every session, one CI job, one developer, or some files?

Reach for it when: You need to give a CI job instructions and must decide whether they belong in CLAUDE.md or the job itself.

Who needs itRight homeWhy
Every session in the repo, CI and laptopsProject CLAUDE.md (+ @import)Committed, always loaded
One CI job onlyJob prompt / --append-system-promptScoped to that run
One developer's preferences~/.claude/CLAUDE.mdPersonal, not shared
Only files matching a pattern.claude/rules/ with paths:Loads when relevant
A task run on demandSkill in .claude/skills/Invoked, not always loaded

Rule to remember: Ask who needs the rule. Everyone working in the repository means project CLAUDE.md; one job means that job's prompt.

Merged from 1 question: Mock 4, scenario 5 question 3

Mind map 53 of 83 · for

53Automated review misses things: reviewer, criteria or size

Ask yourself: Is the miss caused by who reviews, what they are told to look for, or how much they review at once?

Reach for it when: An automated code review in CI misses flaws, raises false positives, or rates severity inconsistently.

What you observeWhere the fault isFix
Misses flaws only in code the same session wroteSelf-review in shared contextIndependent review instance
Independent reviewer misses one kind of flawMissing criterionExplicit criteria + examples
Large PR, uneven depth, contradictionsAttention dilutionPer-file passes + an integration pass
Many false positives in a vague categoryVague instructionCategorical, testable criteria
Severity swings on borderline casesInstructions alone are inconsistentFew-shot examples with reasoning

Rule to remember: If a reviewer misses problems only in code it wrote, separate the reviewer. Add criteria once the reviewer is independent.

Merged from 1 question: Mock 4, scenario 5 question 4

Mind map 54 of 83 · for

54Configuring several CI jobs: real-time, batch and turn limits per job

Ask yourself: Is this job bound by latency, by cost, or does it need a tool loop?

Reach for it when: Several CI jobs share one Claude configuration and their needs pull in opposite directions.

Job typeRight settingWhy
Blocking pre-merge checkReal-time, tight turn limitDevelopers are waiting
Overnight, single pass per fileMessage Batches API50% cheaper, no deadline
Overnight, multi-step tool investigationReal-time calls, generous turn limitBatch can't run tool loops
On-demand generationIts own moderate settingsTolerates minutes
All jobs on one wrapperSeparate invocations per jobOpposite needs

Rule to remember: Configure latency-bound, on-demand and cost-bound jobs separately. Use batch only for single-pass work; it can't run tool loops.

Merged from 1 question: Mock 5, scenario 5 question 8

Back to the list

Domain 4: Prompt engineering and structured output

4.1Explicit criteria and false positives

Mind map 55 of 83 · for

55Too many false positives: write criteria or add examples

Ask yourself: Is the standard for a finding missing, or does it exist but get applied unevenly?

Reach for it when: A review or extraction prompt returns lots of low-value findings, or its output wobbles from run to run.

What you observeWhere the fault isFix
Many low-value findings, the same way every run; the prompt uses a vague word like "thorough" or "careful"No definition of what counts as a findingExplicit, checkable categorical criteria: what to report and what to skip
Prompt says "be conservative", "only if confident" or "high confidence only"Hedging is not a criterion, so precision does not improveReplace it with categorical rules
The team can list exactly what countsWordingWrite the criteria down, with a small code snippet for each
Criteria are clear, but output varies in shape, format or severity run to runRules applied inconsistently; no demonstrated standard2 to 4 few-shot examples that show the reasoning
The boundary is hard to describe in words; ambiguous casesMissing demonstrationLabelled examples with the reasons behind them
Real bugs are caught only on some runsAttention, not criteriaDon't drop them by voting across runs
The generator reviews its own output and misses issuesSelf-review biasIndependent review instance
A big change is reviewed in one pass, with uneven depthAttention dilutionPer-file passes plus an integration pass

Rule to remember: Precision comes from explicit criteria about what to report and what to skip. If you can write the categories down, write them down; use few-shot examples for consistency and for boundaries you can't easily describe.

Merged from 6 questions: Mock 7, scenario 2 question 8; Mock 6, scenario 2 question 7; Mock 6, scenario 6 question 7; Mock 5, scenario 5 question 1; Mock 4, scenario 2 question 9; Mock 4, scenario 5 question 5

Mind map 56 of 83 · for

56Fixing one noisy review category: rewrite, pause or measure

Ask yourself: This one category keeps producing false positives: what kind of fix does it need?

Reach for it when: One review category is mostly false positives and developers are starting to ignore the good findings too.

What you observeWhere the fault isFix
The category has only a vague instruction ("inadequate handling")No definitionCategorical criteria written as specific, testable conditions with code samples
Criteria exist, but borderline cases get a different severity each runInconsistent judgement2 to 4 few-shot examples showing the reasoning
The category is optional, it is noisy, and trust is collapsingTrust erosion, short termPause or temporarily disable the category while it is rewritten
You don't know which patterns are the false positivesMissing dataAdd a detected_pattern field and track dismissals
"Be conservative" or "only high-confidence" was added, with no changeWording is not criteriaReplace it with explicit conditions
Self-reported confidence is used to filter findingsUnreliable proxyCriteria, or calibrated scoring

Rule to remember: To cut false positives, define the category as specific, testable conditions with code samples. Pausing a category is only for optional checks.

Merged from 2 questions: Mock 7, scenario 5 question 6; Mock 6, scenario 5 question 6

Mind map 57 of 83 · for

57Letting the model say it is unsure instead of guessing

Ask yourself: Can the model express doubt, or is it forced to commit to an answer?

Reach for it when: The model always commits to a value, even when the input is unclear or the value is missing.

What you observeWhere the fault isFix
The model always commits; the schema has no "unsure" optionNo way to express doubtAdd a flag or an "unclear" value, plus criteria for using it
The flag exists but is used unevenlyInconsistent judgementFew-shot examples of borderline cases
The value is not on the documentAbsent informationNullable field
A wrong value costs far more than a human reviewRouting thresholdRoute on the flag
Two runs agree on a wrong valueUnreliable proxyDon't use agreement as a check

Rule to remember: If the model can only commit, it will guess. Add an "unsure" outcome, write criteria for using it, and route on it.

Merged from 1 question: Mock 5, scenario 6 question 3

4.2Few-shot examples

Mind map 58 of 83 · for

58Rules or worked examples when output is inconsistent

Ask yourself: Are the rules still vague, or are they clear but the hard cases keep varying?

Reach for it when: You have written instructions, but the output still swings from run to run.

What you observeWhere the fault isFix
Output swings everywhere; levels are adjectives or the instructions are still vagueVague criteriaDefine each level as a checkable test: explicit criteria or a decision table
Rules are concrete, but borderline cases and ambiguous combinations still varyBoundary not demonstrated; prose alone is not enough2 to 4 worked examples showing the reasoning
Judgement calls, and new variants are expectedIntent hard to state as rules2 to 4 varied worked examples with reasoning; they generalise to cases the rules don't cover
A clear rule, and its instances are a small, fixed, known setClear mappingEnumerate them, so the list is complete and checkable
Findings vary in formatFormat not demonstratedExamples of the output format
JSON fails to parse, or fields are missing or the wrong typeSyntax or shapetool_use (or --json-schema) with a tight JSON schema; this fixes structure, not judgement
Content wrong in a way code can detectSemantic errorValidate and retry with the specific error
The model must flag what it cannot decide, or the category set is open-endedUndecidable input or unforeseen valuesEnum with "unclear" or other plus a detail field
Requirements are unknown to the authorMissing informationInterview pattern
The generator misses its own errorsSelf-review biasIndependent review instance

Rule to remember: A schema fixes shape; examples fix content. When detailed instructions stop improving consistency, show 2 to 4 worked examples with the reasoning, and enumerate only stable sets.

Merged from 5 questions: Mock 7, scenario 5 question 7; Mock 6, scenario 2 question 8; Mock 6, scenario 5 question 7; Mock 5, scenario 2 question 9; Mock 4, scenario 5 question 6

Mind map 59 of 83 · for

59Project conventions ignored: are the rules even loading?

Ask yourself: Are the rules actually loaded for these files, or loaded but described poorly?

Reach for it when: Claude Code keeps ignoring a team convention in some files or directories.

What you observeWhere the fault isFix
Convention ignored, and /memory doesn't list its fileRules not loadedFix the home: project CLAUDE.md or .claude/rules/
Rules don't load for some files; the convention spans many directoriesScope: a directory CLAUDE.md is folder-bound.claude/rules/ with a paths: glob
Rules load, but output shape varies on hard casesProse describes structure poorly2 to 4 concrete examples from the codebase
Rules are vague ("handle errors well")Missing criteriaExplicit, checkable criteria
Data arrives in mixed fixed formatsNeeds deterministic normalisationA hook that converts formats
Generated code has bugs a fresh eye would spotSelf-review limitsIndependent review instance

Rule to remember: First check the rules load with /memory. If they do and output still varies, add a few concrete examples covering the hard cases.

Merged from 2 questions: Mock 7, scenario 2 question 7; Mock 5, scenario 5 question 2

Mind map 60 of 83 · for

60Extraction across many document layouts: tailor, route or teach

Ask yourself: Do you know the layouts in advance, and are the field descriptions already clear?

Reach for it when: Extraction accuracy is weak on some documents, layouts or vendors.

SituationRight moveWhy
Field descriptions are thin; errors everywhereExpand the descriptions or state explicit criteriaDefines what counts as the value
Descriptions detailed; a steady stream of varied or unseen layouts2 to 4 few-shot examples chosen for structural variety, with reasoningGeneralises to unseen layouts
Schema fits and definitions exist, but hard cases varyFew-shot examples with reasoningShows how ambiguous cases are handled
A small, fixed set of known vendors with known quirksPer-vendor promptsTailoring pays off
One prompt covers very different document types, with contradicting guidanceClassify, then route to a type-specific promptRemoves conflicts
Field missing from some layoutsNullable fieldPrevents invention
Values don't fit the schemaother plus a detail fieldRoom for unforeseen values
Errors detectable by recomputationValidate and retry with the errorSemantic error
Accuracy must be validated before automating, or errors hit only some doc typesMeasure by document type and fieldAverages hide weak strata

Rule to remember: Pick few-shot examples from where the model fails, showing varied structures and how fields were found. Per-case notes grow with every case and do nothing on day one.

Merged from 4 questions: Mock 7, scenario 6 question 4; Mock 6, scenario 6 question 8; Mock 5, scenario 6 question 10; Mock 4, scenario 6 question 5

4.3Structured output and JSON schemas

Mind map 61 of 83 · for

61Broken JSON or wrong value: what a schema does and doesn't catch

Ask yourself: Is the structured output wrong in its syntax, its format, or its meaning?

Reach for it when: Structured output is bad and you need to know whether a stricter schema will help.

What you observeKind of errorFix
Trailing commas, bad quotes, preamble, missing fieldsSyntax or shapeTool use with a strict JSON schema (forced tool)
Value has the wrong format (bad length, letters in a number)FormatPattern constraints in the schema
Valid JSON, impossible value (line 412 of a 300-line file)SemanticValidate in code and retry with the specific error; cross-check calculated_total against stated_total
Required field filled with invented dataSchema forces a valueMake the field nullable
The model answers in prose, with no tool callTool choicetool_choice "any" or forced
Field truly absent from the sourceMissing informationDon't retry; make it nullable and route to a person
Errors cluster in some fieldsField-specificField-level accuracy measurement

Rule to remember: Tool use with a strict schema stops broken JSON, not wrong values. Once it is in place, the remaining errors look correct, so check meaning in code.

Merged from 2 questions: Mock 5, scenario 6 question 1; Mock 4, scenario 5 question 9

Mind map 62 of 83 · for

62Value absent, unlisted or unreadable: which schema escape hatch

Ask yourself: What does the document actually say about this field: nothing, something the list doesn't cover, or something ambiguous?

Reach for it when: The model invents values, or a real value doesn't fit the enum or required fields.

What the document saysSchema fixWhy
Nothing about this field, but the schema requires itMake it nullable or optional, and describe when to leave it emptyRequired means 'produce something'; this removes pressure to fabricate
Field optional, but the model still fills itFew-shot examples showing nullBehaviour, not structure
A clear value outside a mostly fixed or growing listEnum plus other plus a detail stringKeeps validation and records the value without coercion
A small, known, stable set of extra valuesAdd them to the enumThe closed set stays closed
Text that can't be read with confidence, or is ambiguous between two listed optionsunclear plus a detail field, or examplesFlags ambiguity instead of forcing a choice
A clear value that fits, but is mapped inconsistently or lands in the wrong fieldFew-shot samples, or retry with the specific errorTeaches the mapping
Values entirely free-formString field, normalise laterNo list exists
Value printed but sometimes misreadValidate against the system of record and retryCatches wrong readings
Value present but unreadable in the scanRoute to a personSource quality, not schema
Totals do not add upcalculated_total plus a conflict flagReports the mismatch

Rule to remember: Absent value plus required field means fabrication, so make the field nullable first. Use null when the document says nothing, other plus detail when it says something clear the list doesn't cover, and unclear when the text itself is ambiguous.

Merged from 5 questions: Mock 7, scenario 6 question 1; Mock 7, scenario 6 question 2; Mock 6, scenario 6 question 4; Mock 4, scenario 6 question 1; Mock 4, scenario 6 question 2

Mind map 63 of 83 · for

63Making the model call the right tool: tool_choice settings

Ask yourself: Must the reply be a tool call, and if so, which tool exactly?

Reach for it when: The model replies in text when you need a tool call, picks the wrong tool, or skips a step that must run first.

What you need or observeSetting or fixNote
The model may answer in text or call a toolautoThe default
Must call a tool; it picks the right one when it calls, but text sometimes slips throughtool_choice: "any"Fine when only one tool fits
Must call a tool; several are attached, or a specific step must run firstForced {"type":"tool","name":...}Names the exact tool, for example metadata before enrichment
Empty result must still be structuredForced tool plus an empty array in the schemaNo prose to parse
The model picks the wrong toolBetter descriptions, or classify then forceA selection problem
Tools have one-line descriptionsAdd inputs, examples and boundariesDescriptions drive selection
Must never call a tool in some stepRestrict the available toolsThe choice is too open

Rule to remember: auto allows text; "any" requires some tool; forced requires that tool. If selection is right and only text slips through, use any; with several tools attached, force the one you need.

Merged from 2 questions: Mock 6, scenario 6 question 6; Mock 5, scenario 5 question 9

4.4Validation, retry and feedback

Mind map 64 of 83 · for

64Validation failed: retry with feedback or hand off to a person

Ask yourself: Is the answer actually in the document for a retry to find?

Reach for it when: Validation fails and retries keep failing, or someone proposes another retry.

What failedInformation in source?Right move
Fields mapped wrongly, misformatted, or a sum mismatch fixed on attempt twoYesRetry with the specific validation errors appended
The retry message is generic ("try again")YesReplace it with specifics first; blind feedback gives nothing new to act on
Value present but printed in an unusual place on some layoutsYesFew-shot examples of those layouts
Required value not on the documentNoStop retrying; nullable field and route to a person
Value illegible in the scanNo (not readable)Route to a person
Invented values appear after retriesNoStop retrying; allow null, since a required field creates pressure to fill it
Model miscalculates a fact you could computeYesGive it the computed fact
Subtle logic or judgement errors that no tool reportsYesIndependent review instance, if the budget allows
JSON won't parse, or output format is inconsistentYesTool use with a schema for syntax; few-shot examples for format

Rule to remember: Retry with the specific errors when the fix is reachable in the source. Retries can't create missing information, so when it is absent, stop retrying and route to a person.

Merged from 6 questions: Mock 7, scenario 5 question 9; Mock 7, scenario 6 question 3; Mock 6, scenario 5 question 10; Mock 6, scenario 6 question 5; Mock 5, scenario 6 question 2; Mock 4, scenario 6 question 4

Mind map 65 of 83 · for

65Catching tidy-but-wrong values: where the check must live

Ask yourself: Could the model hide this mismatch, and what outside check can catch a wrong value that looks right?

Reach for it when: Values are well-formed and pass the schema but are wrong, or numbers don't reconcile.

SituationRight mechanismWhy
The model smooths mismatches before returningExtract stated total, calculated total and a conflict flagThe mismatch becomes data
Extraction reports figures as printedRecompute in code and hold on mismatchA deterministic check works
Stop wrong values on each documentCross-check against business recordsAn outside source of truth
Send only doubtful items to peoplePer-field confidence, calibrated on labelled dataScores that mean something
Learn error rates by field or document typeStratified sampleMeasures, but doesn't stop errors
Is the model sure?Not self-reported confidencePoorly calibrated
Do two runs agree?Not a correctness checkSame mistake twice
Two sources disagreeKeep both, with attributionDon't pick one silently
Value absent from the documentNullable fieldNo fabrication

Rule to remember: If the model can hide a mismatch, make it report one: stated total, calculated total, conflict flag. Self-reported confidence and run agreement don't measure correctness; outside records and calibrated per-field confidence do.

Merged from 2 questions: Mock 5, scenario 6 question 9; Mock 4, scenario 6 question 3

Mind map 66 of 83 · for

66Measuring which review rules produce false positives

Ask yourself: Who supplies the judgement of whether a finding was wrong: developer actions, or labelled samples?

Reach for it when: You want per-category false-positive rates before tuning or automating a review.

SituationRight mechanismWhy
Need per-category rates, no human labellingdetected_pattern on each finding, with dismissals logged by IDUses developer clicks as the signal
Need a true precision estimate, and reviewer time is availableStratified sample per categoryLabels are judged, not inferred
Automating one high-stakes categoryStratified sample of that category firstThe aggregate hides it
One category is mostly false positivesRewrite that category's criteriaNoise erodes trust in good findings
Want a second opinion on hard casesIndependent review instanceNo generation bias

Rule to remember: To find which rules are noisy, tag each finding with its rule and record each dismissal against it. Then the rate per rule is a query.

Merged from 1 question: Mock 5, scenario 5 question 5

4.5Batch processing

Mind map 67 of 83 · for

67Batch or real-time: who is waiting, and by when

Ask yourself: Is anyone blocked on the result or bound by a deadline, and does each item need a tool loop?

Reach for it when: You are choosing between the Message Batches API and normal synchronous requests for a workload.

SituationRight choiceWhy
Overnight report read next morning, weekly audit, or advisory review nobody waits onMessage Batches API, matched by custom_idLatency-tolerant; 50% cheaper
Large single-call extraction, deadline days awayMessage Batches API plus custom_id50% cheaper, results within 24 hours
Required pre-merge checkSynchronous (real-time) requestsA merge waits on it, and batch has no latency guarantee
Non-blocking, but a person must act within a deadline, or results are needed within hoursReal-time, in parallel if needed (for example parallel subagents)Batch has no latency SLA
Each item needs multi-turn tool callingReal-time, or pre-fetch the tool dataBatch has no tool loop per request
Live traffic must keep flowing during a backfillKeep the backfill separateDon't compete with users

Rule to remember: Batch saves 50% but promises nothing about time. Batch only work that nobody waits on by a deadline; non-blocking is not the same as latency-tolerant.

Merged from 3 questions: Mock 7, scenario 6 question 5; Mock 6, scenario 5 question 8; Mock 4, scenario 5 question 7

Mind map 68 of 83 · for

68Working inside batch limits: tool calls, matching results, failures

Ask yourself: What can a batch request not do, and how do you tie each result back to its input?

Reach for it when: A batch request stops at tool_use, results come back in a different order, or some requests fail.

SituationRight moveWhy
Results must be matched to their inputsA custom_id on every requestResult order is not guaranteed
Some batch items failedResubmit only those, by custom_idNo need to redo the batch; keeps the 50% saving
Tool data is predictable and available beforehandPre-fetch it into each batch requestKeeps the 50% saving
The model must decide what to look up as it goesSynchronous requests with a tool loopBatch has no multi-turn tool calling
Output cut off mid-answer (max_tokens)Raise max_tokensA length problem, not a tools problem
The model answers in text instead of calling a tooltool_choice "any" or forcedGuarantees a call

Rule to remember: Batch requests can't run tool loops, and results come back in any order. Pre-fetch predictable tool data, match on custom_id, and resubmit only the failed IDs.

Merged from 2 questions: Mock 5, scenario 5 question 6; Mock 4, scenario 5 question 8

Mind map 69 of 83 · for

69Cutting cost without losing coverage

Ask yourself: Which cost levers keep the output complete?

Reach for it when: You are asked to cut the cost of a Claude workload without breaking what it must cover.

LeverWhen it fitsWatch out for
Message Batches APINobody waits on results (overnight, weekly)No latency SLA; no multi-turn tools
Trim input to the fields the task usesRequests carry content the task ignoresDon't drop what's used
Skip unchanged itemsOld results stay validBreaks full-coverage requirements
Pack many items per requestRarelyAttention dilution, contradictions
Real-time requestsSomeone waits (pre-merge)Full price

Rule to remember: Batch what nobody waits for; trim what the task doesn't read. Don't skip work a requirement says to cover.

Merged from 1 question: Mock 7, scenario 5 question 8

4.6Multi-pass review

Mind map 70 of 83 · for

70Why a review misses bugs: self-review, dilution or unclear criteria

Ask yourself: What shape are the misses, and what differs between a reviewer that finds them and one that doesn't?

Reach for it when: A code review (often in CI) misses bugs, gives uneven depth, or produces output the next step can't use.

What you observeWhere the fault isFix
Same prompt; a fresh session finds bugs, the author session doesn'tSelf-review biasIndependent instance with no prior context or generation history
Longer or deeper thinking proposed for the same session's self-reviewStill self-review: same bias, more wordsStill use an independent instance
Large change reviewed in one pass; uneven depth, thin in the middleAttention dilutionSplit into per-file passes
Each file looks fine, but files disagree, or feedback contradicts itself across a large PRNo pass sees across filesAdd a cross-file integration pass
Every session misses the same kind of bug, or an independent reviewer misses one categoryUnclear criteria or no examplesExplicit review criteria, then few-shot examples
Reviewer lacks project standardsMissing contextPut the standards in CLAUDE.md
Review comments inconsistent in formatNo pattern to followFew-shot examples
Review hangs waiting for input in CIInteractive modeclaude -p
Findings must become PR comments or feed the next stepOutput format--output-format json plus a schema

Rule to remember: The instance that wrote the code should not review it. Per-file passes catch local bugs, and a separate integration pass catches mismatches between files.

Merged from 4 questions: Mock 7, scenario 5 question 10; Mock 6, scenario 5 question 9; Mock 5, scenario 2 question 10; Mock 4, scenario 2 question 10

Back to the list

Domain 5: Context management and reliability

5.1Keeping key facts in long interactions

Mind map 71 of 83 · for

71Keeping exact facts intact through a long conversation

Ask yourself: What is losing the facts: the summary, the tool output, or where they sit?

Reach for it when: Numbers, promises or findings drift or blur as a conversation or multi-step run gets long.

What you observeWhere the fault isFix
Errors begin well before the window fillsLost in the middle plus noisy tool outputCase-facts block at the top and trimmed tool results
Tool results carry many unused fields (40 returned, 5 used) and dominate the contextVerbose tool outputTrim results to the relevant fields before they enter history (for example in a PostToolUse hook)
Exact amounts and promises blur after summarisation (an amount becomes “declined”)Progressive summarisation: the facts sit inside the history being rewrittenPersistent case-facts block with exact values, carried in every request outside the summary
Facts are present but ignored, buried mid-contextLost in the middlePut key facts first, under a clear heading
An old session is resumed, full of outdated tool resultsStale tool resultsNew session seeded with a structured summary
All the facts already live in a system of recordData already storedRe-read the system of record
History is genuinely being truncatedNot enough roomLarger window (or trim first)
History must stay verbatimCompliance limitAdd structure; don't replace turns
All prior findings fit in the next agent's inputNothing is lost if passed wholePass the complete prior findings in the prompt
Verbose exploration in a coding session, or findings that must survive a crash or restartContext pollution, or the context is volatileSubagent for the exploration; scratchpad or manifest file for the findings

Rule to remember: Fix what fills the context before protecting facts from it: trim tool output to the fields you use. Keep numbers and promises in a case-facts block at the top of every request, and don't trust summaries with them.

Merged from 5 questions: Mock 7, scenario 1 question 10; Mock 6, scenario 1 question 8; Mock 6, scenario 3 question 10; Mock 5, scenario 1 question 6; Mock 4, scenario 1 question 6

Mind map 72 of 83 · for

72Getting the middle of a long input read

Ask yourself: Where do the missed details sit, and is the input already structured?

Reach for it when: The model follows the start and end of a long document or prompt but misses things in the middle.

What you observeWhere the fault isFix
Start and end followed, middle missed; input fits, is lean, and only a few key facts matterLost in the middle, no structureKey summary or digest first, plus explicit section headings
Headings already there, middle still lagsPosition itselfSegment it: one request per part
Many detailed items lost mid-input, or the input is too large or has naturally separate partsToo much at onceSplit into shorter passes, then merge the results
Document doesn't fit at allCapacityChunk it
Input full of irrelevant fields; tool output buries key factsVerbose tool outputTrim to the relevant fields; case-facts block
Numbers, dates and details blur after summarising a long chatLossy (progressive) summarisationKeep exact facts in a fixed, persistent case-facts block
Claims lose their sourcesCompression without mappingStructured claim-source mappings
Mixed document types in one promptInstruction fitClassify and route
Rules vague, results varyMissing criteriaExplicit criteria or examples
Output cut off at the endmax_tokensRaise the limit

Rule to remember: Strong start and end with a weak middle is a position problem: put key points first under clear section headings. If headings are already there, or there is lots of detail, split the input so nothing sits in the middle.

Merged from 4 questions: Mock 7, scenario 2 question 10; Mock 7, scenario 3 question 9; Mock 5, scenario 6 question 8; Mock 4, scenario 6 question 7

5.2Escalation and ambiguity

Mind map 73 of 83 · for

73When the agent should hand over to a person

Ask yourself: Which escalation trigger is actually present?

Reach for it when: You must decide whether the agent resolves a customer's issue itself or escalates it to a human.

SituationAgent shouldWhy
Customer explicitly asks for a personEscalate immediately, with a handoff summaryAn explicit demand is a trigger
Customer frustrated or angry but hasn't asked; issue is simple and in scopeAcknowledge and offer the fix; escalate if they then ask againFrustration is not complexity
Policy is silent or needs an exceptionEscalatePolicy gap
Agent cannot make progressEscalate with a structured handoffInability to progress
Escalation driven by sentiment or self-rated confidenceReplace with categorical triggersUnreliable proxies
Several accounts match the nameAsk for an identifierDon't guess

Rule to remember: Escalate on categories: an explicit request for a person (at once, with the facts), a policy gap, or no progress. Frustration alone means offer resolution first; tone and self-rated confidence are not triggers.

Merged from 2 questions: Mock 7, scenario 1 question 8; Mock 5, scenario 1 question 4

Mind map 74 of 83 · for

74Fixing an escalation boundary that misfires

Ask yourself: What is the cheapest fix that makes the escalation boundary clear?

Reach for it when: The agent escalates easy cases and keeps going on hard ones, or someone proposes a new signal to route escalations on.

SituationRight mechanismWhy
Guidance is vague; errors in both directions (easy cases escalated, hard ones kept)Explicit criteria plus a few contrasting examplesClarifies a fuzzy boundary cheaply and proportionately
Clear criteria and examples exist and still fail; there is a large labelled history and time to build and maintain a modelConsider a separate trained classifierHeavier; proportionate only after the cheap fix and at that scale
Proposal: route on self-rated confidenceRejectPoorly calibrated to complexity
Proposal: escalate on anger or sentimentRejectSentiment is not complexity
Customer explicitly asks for a personEscalate immediatelyAn explicit demand is a trigger
Human receiving an escalation lacks contextStructured handoff summaryImproves the handoff, not the decision

Rule to remember: Fuzzy escalation boundaries get explicit criteria plus a few contrasting examples, not a new model. Self-rated confidence and sentiment don't measure complexity.

Merged from 2 questions: Mock 6, scenario 1 question 10; Mock 4, scenario 1 question 5

Mind map 75 of 83 · for

75Which customer record to act on

Ask yourself: What is the source of truth for who this customer is?

Reach for it when: A customer's name matches account records and the agent must decide whose account to act on.

What you observeWhere the fault isFix
Chat arrives with a signed-in, verified accountIdentity already knownUse that account
Name matches several records, guest chatAmbiguous lookupReturn all matches; ask for an order number or postcode
Name matches exactly one recordNo ambiguityProceed, verifying as policy requires
Refund attempted before identity is verifiedOrderingPrerequisite gate on get_customer
Ranking or confidence used to pick a matchHeuristic selectionReplace with a question to the customer

Rule to remember: Several matching records means ask the customer for an identifier. Do not choose by recency, score or ranking.

Merged from 1 question: Mock 5, scenario 1 question 5

5.3Errors across agents

Mind map 76 of 83 · for

76Handling and reporting a subagent's failed or empty lookup

Ask yourself: Did the lookup actually run, and should the subagent handle the error itself or hand it up?

Reach for it when: A subagent's search or lookup returns nothing, times out or errors, and the coordinator must decide what to do next.

What happenedSubagent shouldWhy
Lookup succeeded and found nothingReturn a valid empty result; don't retryNot an error; the coordinator can act on it
Brief transient blip or timeoutRetry locally with backoff, then reportLikely to succeed soon
Lookup failed and won't clear soon (timeout, outage)Report a structured error: failure type, query tried, partial results, alternativesThe coordinator chooses the recovery: hold, escalate or retry later
Bad input to the lookupReport a validation errorThe coordinator can fix and resend
Generic “search unavailable” statusAnti-patternHides what was tried and what remains
Crash on any failureAnti-patternDiscards other agents' work

Rule to remember: Never let a failed lookup look like an empty one. Handle brief glitches locally; hand up longer failures with the failure type, the query, partial results and alternatives.

Merged from 2 questions: Mock 7, scenario 1 question 9; Mock 7, scenario 3 question 10

5.4Context in large codebases

Mind map 77 of 83 · for

77What to do when a long session fills up or degrades

Ask yourself: Is the session just full, or has it degraded, and what is flooding it?

Reach for it when: A long coding session is filling up, slowing down, or giving vague and contradictory answers.

What you observeWhere the fault isFix
Nearly full, answers still specific; only the gist is needed from hereSpace only (one-off build-up of history)/compact
Answers vague, “typical patterns”, contradictions; specifics still neededContext degradationWrite findings to a scratchpad or notes file; a fresh session reads it
Repeated verbose output (logs, test runs) floods the contextVerbose work done in the main sessionDelegate to a subagent that returns a summary
Exploring an unfamiliar codebase, lots of reading still to doVerbose discoveryExplore subagent returning summaries
Coming back after files changed; earlier tool results are staleStale contextNew session from a structured summary
Progress must persist across a session boundaryNothing written outside the chatScratchpad or progress file
Long job may crash or be interrupted mid-wayNo recovery stateManifest or progress file
One long review thins out in the middleAttention dilutionSplit into focused passes

Rule to remember: If the session is healthy but full, use /compact. If it has degraded or the work crosses sessions, write the findings to a file and start a fresh session from it, and send noisy, repeated work to a subagent that returns only a summary.

Merged from 3 questions: Mock 7, scenario 2 question 9; Mock 6, scenario 2 question 10; Mock 5, scenario 2 question 8

Mind map 78 of 83 · for

78Carrying long work across a break, crash or handover

Ask yourself: What carries the state forward: the conversation, a file on disk, or a fresh summary?

Reach for it when: Long work must be picked up after a pause or crash, or handed to another person or machine.

SituationRight mechanismWhy
Findings needed across sessions or by another personScratchpad file in the repoPersists outside the chat
Crash or interruption in a long job, files changed sinceState manifest or progress file, read on restartThe conversation is stale; restart from saved state
Same person, same machine, nothing or few changes since the pause--resume the named session, plus a note of what changedHistory is still mostly valid
Resuming after edits you made yourselfTell the agent which files changedIt is unaware of the changes
Earlier tool results largely stale, or the work moves machinesNew session from a structured summaryAvoids stale tool results
Try two approaches from one starting pointfork_sessionDivergence from a shared start
Session long and full, but work continues now or ends today/compact (or scratchpad plus fresh session)Frees space in place, loses some detail
Big noisy search or verbose explorationExplore subagentReturns summaries only

Rule to remember: Keep progress for long work in a file on disk outside the chat, and start fresh from a summary when much has changed. A resumed conversation remembers what was said, not what is on disk now.

Merged from 3 questions: Mock 6, scenario 2 question 9; Mock 5, scenario 2 question 7; Mock 4, scenario 2 question 7

Mind map 79 of 83 · for

79Keeping noisy search output out of the main context

Ask yourself: Is the noise predictable enough to exclude, or does it need filtering somewhere else?

Reach for it when: A codebase search returns far more output than you need.

SituationRight mechanismWhy
Noise under predictable pathsExclusion globs on the searchCheapest, precise
Noise scattered, no patternExplore subagent filters in its own contextMain chat stays clean
Looking for files by nameGlobPaths, not contents
Looking for text inside filesGrepContent search
Context already flooded, work ends soon/compactRecovers space, may blur details

Rule to remember: Send noisy discovery to an Explore subagent that returns a short summary. Narrow the search instead only when the noise sits under predictable paths.

Merged from 1 question: Mock 4, scenario 2 question 8

5.5Human review and confidence

Mind map 80 of 83 · for

80Proving a category is ready to skip human review

Ask yourself: Which number do you actually have, and does it cover the category you plan to automate?

Reach for it when: Someone wants to automate extraction or review because headline accuracy looks high.

SituationRight stepWhy
High overall accuracy, but the target type is a small slice or rare in the sampleStratified sample of that type (and by field); give rare, high-impact types a quotaAverages hide weak categories; too few samples to judge
Per-category figures exist for some categoriesAutomate only thoseOnly those categories are proven
Type's accuracy is known; errors cluster on certain fields, or individual items must be routedField-level confidence calibrated on labelled data that covers every typeRoutes only uncertain values to review
Only the model's self-reported confidenceDon't route on it until it is calibrated on labelled dataSelf-reports are poorly calibrated
Two runs or two independent extractors agreeStill measure against labelsAgreement shows repeatability, not correctness; double cost and no per-type rate
Larger uniform sampleUse it for the overall number onlyStill hides rare types
After launch, watching error rates in confident output over timeStratified random sampling of high-confidence itemsCatches drift that confidence hides
Which rules are noisy?detected_pattern plus dismissal trackingGives per-pattern rates
Calculated vs stated figures cross-checkUse it as a consistency checkCatches some errors, measures nothing
A hard money limitHook that blocks and escalatesEnforces the rule; says nothing about quality

Rule to remember: An overall score is not a per-category score. Before automating, measure each type you plan to automate with a stratified sample; calibrated field-level confidence comes after, for routing, and stratified sampling keeps watch after launch.

Merged from 6 questions: Mock 7, scenario 6 question 9; Mock 6, scenario 1 question 9; Mock 6, scenario 6 question 10; Mock 5, scenario 5 question 10; Mock 4, scenario 5 question 10; Mock 4, scenario 6 question 6

5.6Sources, provenance and uncertainty

Mind map 81 of 83 · for

81Finding where a citation lost its source

Ask yourself: At which stage did the claim lose the link to its source?

Reach for it when: A report's citations are missing, guessed or pointing to the wrong source.

What you observeWhere the fault isFix
Findings arrive as prose with sources named in passing; summaries have no document or page infoResearch or analysis output formatStructured fields (claim, URL, title, page), with content kept separate from metadata
Citations guessed after the prose is written; synthesis rewrites and drops the linksSynthesis hand-offEmit claim-to-source mappings and pass them through as data
Links are carried, but a few are still wrongOccasional model errorIndependent review pass before release
Pipeline cannot change, and time is availableDetection onlyVerify each citation against its page
Two reputable sources disagree on one figure; one chosen silentlyConflict handling, not attributionShow both, each with its source
Figures look contradictory but differ by dateMissing datesRecord publication and collection dates

Rule to remember: Provenance is carried, not recovered: structure claim-to-source mappings where they start and keep them through every hand-off. Rebuilding attribution after the fact is guessing.

Merged from 2 questions: Mock 5, scenario 3 question 5; Mock 4, scenario 3 question 5

Mind map 82 of 83 · for

82Reporting figures when sources disagree

Ask yourself: Is this a genuine conflict or a change over time, and what does the reader need?

Reach for it when: Two or more sources give different values for the same figure.

SituationRight handlingWhy
Figures cover different periods or yearsRecord publication and collection dates; compare like periodsA time difference is not a contradiction
Values carry effective dates that order themKeep all with dates; the current value is the latest effective oneA sequence (a history), not a contradiction
Same period, both reputable, still differ (two values in force at once)Show both, each with source, date and method, in a structured section; note the conflict and let a human decidePicking one arbitrarily hides information
Values lack datesAnnotate with sources and flagThey can't be ordered
The system itself must resolve a gap in evidenceRe-delegate a targeted search, then re-synthesiseFills gaps when resolution is the system's job
A figure cannot be found in its sourceVerify against the sourceBad extraction or citation
Claims lose their sources in summariesClaim-to-source mappings through synthesisAttribution survives synthesis
Reviewers have limited time and need to focus itCalibrated confidence routes weak claims to reviewDirects human effort
Mixed content types (financial data vs news)Render financial data as tables, news as proseEach type is read correctly

Rule to remember: Check the dates before calling it a contradiction. When good sources genuinely disagree, show both with their sources and dates and let the reader judge; don't pick a winner.

Merged from 4 questions: Mock 6, scenario 3 question 9; Mock 6, scenario 6 question 9; Mock 5, scenario 3 question 7; Mock 4, scenario 3 question 6

Mind map 83 of 83 · for

83Speeding up human review of extracted values

Ask yourself: Where is the reviewers' time going, and what would save it?

Reach for it when: People checking extracted values are slow.

Where time goesWhat helpsMechanism
Finding where each value came fromSource location per valuePage + quoted text (provenance)
Deciding which fields to checkPrioritisationCalibrated confidence, low first
Understanding a long document's layoutOrientationSummary + section headers
Reconstructing why a value was chosenRationaleBrief reasoning per value
Conflicting values across documentsAttribution of eachKeep both with source and date

Rule to remember: When people verify extracted values, give each value its source: the page and the exact text.

Merged from 1 question: Mock 7, scenario 6 question 10

Back to the list

Next

Practise with them

Try a mind map on a fresh question: Mock 7, plain style is the best place to start, and Mock 6 is the stretch. Each trap on its own: the trap gym.