Subagent Troubleshooting & Advanced Patterns

Core coordination patterns are in CLAUDE.md

<subagent_coordination>

When to Load This Skill

• Subagent returned malformed output twice
• Need voting pattern for critical/irreversible decision
• Debugging why coordination isn't working
• Learning TOON format syntax details

Voting for Critical Decisions

For irreversible actions (deletions, deployments, security assessments), run same query 2-3 times in parallel:

<!-- 3 parallel agents, same question -->
<invoke name="Task">
  <parameter name="subagent_type">Explore</parameter>
  <parameter name="model">haiku</parameter>
  <parameter name="prompt">@type: AssessAction about: "safe to delete auth_old.ts" ...</parameter>
</invoke>
<invoke name="Task">
  <parameter name="subagent_type">Explore</parameter>
  <parameter name="model">haiku</parameter>
  <parameter name="prompt">@type: AssessAction about: "safe to delete auth_old.ts" ...</parameter>
</invoke>
<invoke name="Task">
  <parameter name="subagent_type">Explore</parameter>
  <parameter name="model">haiku</parameter>
  <parameter name="prompt">@type: AssessAction about: "safe to delete auth_old.ts" ...</parameter>
</invoke>

Interpret results:

• 3 agree → proceed confidently
• 2 agree → proceed with caution, note dissent
• All differ → query is ambiguous, refine and retry

Red-Flag Recovery

Never: Try to parse/repair confused output. Discard and retry.

TOON Format Reference

Token-Oriented Object Notation. Use for uniform arrays (file lists, steps, configs).

Basic Syntax

# Array with header declaring fields
items[N]{field1,field2,field3}:
  value1,value2,value3
  value1,value2,value3

Escaping

• Commas in values: wrap in quotes

  "value, with comma"

• Quotes in values: escape

  \"nested quote\"

• Newlines: use

  \n

Examples

File list:

files[3]{path,purpose,lines}:
  src/auth/login.ts,Main login handler,145
  src/auth/session.ts,Session management,89
  src/auth/token.ts,JWT utilities,67

Process steps:

steps[4]{position,action,file}:
  1,Parse request body,src/middleware/parser.ts
  2,Validate auth token,src/middleware/auth.ts
  3,Check permissions,src/middleware/rbac.ts
  4,Execute handler,src/routes/api.ts

Key-value config:

config[3]{key,value}:
  maxTokens,1500
  format,toon
  itemLimit,10

Anti-Patterns Checklist

If coordination isn't working, check for these:

@constraints: maxTokens: N

Decomposition Examples

Bad: Compound task

Find authentication code and analyze security vulnerabilities and suggest fixes

Good: Three focused agents

Agent 1: Find authentication code (haiku, 1500 tokens)
Agent 2: Analyze security of [files from agent 1] (sonnet, 2000 tokens)
Agent 3: Suggest fixes for [issues from agent 2] (sonnet, 2000 tokens)

Note: Agent 2 depends on Agent 1, so run sequentially. But if you had 3 independent searches, run all in parallel.

Quick Diagnostics

Subagent returned garbage
├─ Was format specified? → Add explicit TOON/JSON instruction
├─ Was budget set? → Add @constraints maxTokens
├─ Was task atomic? → Check for "and", split if needed
├─ Right model? → Simple task shouldn't use opus
└─ Second failure? → Escalate model or refine query

External Data Operations

MCP tools and web scrapes are context pollution hazards:

firecrawl_scrape

firecrawl_search

WebFetch

Rule: Any task involving N external fetches should be delegated with:

• Token budget:

  min(N × 200, 2500)

  tokens for summary output
• Format: TOON for uniform results, JSON for complex analysis
• Scrape options:

  onlyMainContent: true

  ,

  formats: ["markdown"]

Example - URL verification:

Task(Explore, sonnet):
  "Verify these 10 legislation URLs. For each, scrape with onlyMainContent:true,
   confirm HTTP 200, identify managing authority from page content.

   @return ItemList in TOON:
   results[10]{jurisdiction,url,status,authority}:
     Commonwealth,https://legislation.gov.au,valid,Office of Parliamentary Counsel
     ...

   @constraints: maxTokens: 2000"

Reference

• Core patterns:

  CLAUDE.md

  <subagent_coordination>

• TOON format details:

  references/toon-format.md

• Source: "Solving a Million-Step LLM Task with Zero Errors" (arxiv:2511.09030)