Pass the CCAR-F together.

The agentic loop (§1.1)

Send request → inspect stop_reason → if tool_use: execute the tools, append results to conversation history, loop; if end_turn: done. The model decides the next tool from context — that model-driven choice is what makes it "agentic" vs a pre-wired decision tree.

Coordinator–subagent orchestration (§1.2–1.3)

• Hub-and-spoke: all inter-subagent communication routes through the coordinator — observability, consistent error handling, controlled information flow.
• Context isolation: subagents inherit nothing. Pass prior findings, source metadata, and quality criteria explicitly in the subagent prompt; use structured formats to separate content from metadata (URLs, doc names, page numbers) so attribution survives.
• Spawning: the Task tool spawns subagents; the coordinator's allowedTools must include "Task". Parallelism = multiple Task calls in a single response, not across turns.
• Coordinator prompts state goals and quality criteria, not step-by-step procedure — subagents need room to adapt. Watch for too-narrow decomposition (the "creative industries → only visual arts" failure).
• Dynamic routing: a good coordinator selects which subagents a query needs rather than always running the full pipeline.

Enforcement: hooks vs prompts (§1.4–1.5)

• Prerequisite gates: programmatically block process_refund until get_customer returned a verified ID.
• Tool-call interception: block policy violations (refund > $500) and redirect to escalation.
• PostToolUse hooks: normalize heterogeneous tool output (Unix timestamps, ISO 8601, numeric status codes) before the model sees it.
• Handoffs: escalating to a human who can't see the transcript? Compile a structured summary — customer ID, root cause, amounts, recommended action.

Decomposition & sessions (§1.6–1.7)

Tool descriptions are the routing layer (§2.1)

Descriptions are the primary mechanism for tool selection. Minimal or overlapping descriptions cause misrouting. The fix hierarchy: enrich descriptions first (inputs, example queries, edge cases, boundaries vs similar tools) — before few-shot examples, routing layers, or consolidation. Also audit system prompts for keyword-sensitive wording that hijacks selection, and split generic tools into purpose-specific ones with clear I/O contracts.

Structured errors (§2.2)

Tool distribution & tool_choice (§2.3)

• Too many tools (18 vs 4–5) degrades selection; scope each agent to its role. Out-of-role tools get misused (a synthesis agent running web searches).
• High-frequency cross-role need? Give a scoped tool (e.g. verify_fact for the synthesis agent); complex cases still route via coordinator.
• Constrain risky generic tools: replace fetch_url with load_document that validates URLs.

MCP configuration (§2.4)

• Project scope .mcp.json → shared team tooling, version-controlled. User scope ~/.claude.json → personal/experimental. Both load simultaneously; tools discovered at connection time.
• Secrets: env-var expansion ${GITHUB_TOKEN} in .mcp.json — never commit credentials.
• MCP resources expose content catalogs (schemas, issue summaries, doc hierarchies) so agents don't burn exploratory tool calls.
• Prefer community servers for standard integrations (Jira); build custom only for team-specific workflows. Write rich MCP tool descriptions or the agent will prefer built-ins like Grep.

Built-in tool selection (§2.5)

Where does configuration live? (§3.1–3.3)

Skill frontmatter (§3.2)

• context: fork — run in an isolated sub-agent context so verbose output doesn't pollute the main conversation.
• allowed-tools — restrict tool access during the skill (e.g. no file writes).
• argument-hint — prompt developers for required parameters.
• Personal variant of a team skill? Create it under ~/.claude/skills/ with a different name.

Plan mode vs direct execution (§3.4)

Iterative refinement (§3.5)

• Concrete input/output examples beat prose when descriptions get interpreted inconsistently — give 2–3.
• Test-driven iteration: write the test suite first, share failures to steer improvement.
• Interview pattern: have Claude ask questions first to surface considerations (cache invalidation, failure modes) in unfamiliar domains.
• Interacting problems → one detailed message; independent problems → fix sequentially.

CI integration (§3.6)

• claude -p "…" (--print) = non-interactive mode; without it the CI job hangs waiting for input.
• --output-format json + --json-schema = machine-parseable findings for inline PR comments.
• CLAUDE.md supplies CI context: testing standards, fixtures, review criteria.
• An independent Claude instance reviews better than the session that wrote the code (it carries generation bias). Re-running after new commits? Include prior findings; ask only for new/unaddressed issues. Provide existing test files so generation doesn't duplicate coverage.

Precision prompting (§4.1–4.2)

• Explicit categorical criteria ("flag a comment only when it contradicts actual code behavior") beat vague dials ("be conservative", "high-confidence only") — those don't move precision.
• False positives destroy trust in accurate categories too. Triage: temporarily disable the noisy category while you fix its prompt; define severity levels with concrete code examples.
• Few-shot examples are the top technique for consistent format and for teaching judgment on ambiguous cases: 2–4 targeted examples showing why one action beat the plausible alternative; include desired output format (location, issue, severity, fix); show acceptable vs genuine-issue pairs; demonstrate varied document structures. Reduces extraction hallucination.

Structured output via tool_use (§4.3)

• tool_use + JSON schema = guaranteed schema-compliant output, no JSON syntax errors. But it doesn't prevent semantic errors — line items can still not sum to total, values can land in the wrong fields.
• Nullable/optional fields for info the document may lack — required fields force the model to fabricate. Enums get "unclear" and "other" + detail string for extensibility.
• Self-validation flows: extract calculated_total alongside stated_total; add conflict_detected booleans.

Validation & retry (§4.4)

Add detected_pattern fields to findings so dismissed false positives can be analyzed systematically.

Batch processing (§4.5)

• Fit: non-blocking, latency-tolerant work (overnight reports, weekly audits, nightly test generation). Never for blocking pre-merge checks — those stay synchronous.
• SLA math: 30-hour delivery promise with 24-hour processing → submit every 4–6 hours.
• Failures: resubmit only failed docs (by custom_id), modified (e.g. chunk oversized docs). Refine prompts on a sample before batching the full volume.

Multi-instance & multi-pass review (§4.6)

• A model reviewing its own output keeps its generation reasoning — an independent instance without that context catches more.
• Large reviews: per-file passes for local issues + a separate cross-file integration pass; avoids attention dilution and contradictory findings.
• Have the model self-report confidence per finding to route review — but calibrate against labeled data (see D5).

Keeping the important stuff in context (§5.1, §5.4)

• Progressive summarization risk: numbers, percentages, dates, customer-stated expectations blur into vague summaries. Fix: extract transactional facts into a persistent "case facts" block included in every prompt, outside summarized history.
• Lost in the middle: models process the beginning and end of long inputs reliably; middles get dropped. Put key-findings summaries first; use explicit section headers.
• Trim verbose tool outputs to relevant fields (40-field order lookups when 5 matter) before they accumulate.
• Long exploration: scratchpad files persist findings across context boundaries; subagents isolate verbose discovery; summarize each phase before the next; /compact when context fills; crash recovery via structured state manifests the coordinator reloads on resume.

Escalation (§5.2)

• Frustrated but resolvable? Acknowledge, offer the fix, escalate only if they insist again.
• Multiple customer matches → ask for more identifiers, never pick heuristically.
• Add explicit escalation criteria with few-shot examples to the system prompt.

Error propagation in multi-agent systems (§5.3)

Subagents recover locally from transient failures; what they can't resolve they propagate with structured context: failure type, attempted query, partial results, viable alternatives. Coordinator can then retry-modified, reroute, or proceed-with-gaps. Synthesis output carries coverage annotations: which findings are well-supported vs gapped by unavailable sources.

Human review & confidence calibration (§5.5)

• 97% aggregate accuracy can hide a failing document type or field — segment accuracy by type and field before automating anything.
• Stratified random sampling of high-confidence extractions measures ongoing error rates and catches novel patterns.
• Field-level confidence scores are only useful after calibration against labeled validation sets; route low-confidence and contradictory-source extractions to limited reviewer capacity.

Provenance & multi-source synthesis (§5.6)

• Summarization loses attribution unless subagents emit claim-source mappings (URL, doc name, excerpt) that synthesis must preserve and merge.
• Credible sources conflict? Annotate both with attribution — never silently pick one. Require publication dates so temporal differences aren't read as contradictions.
• Render by content type: financial data as tables, news as prose, technical findings as structured lists. Distinguish well-established vs contested sections.