name: researching-with-subagents description: Use when needing to look up documentation, research libraries/frameworks, or gather information about any technology - dispatches sub-agents for all research to preserve context and ensure proper source citation

Researching with Sub-agents

Overview

ALL research tasks MUST use sub-agents. Research means looking up documentation, searching for information, or investigating how technologies work. Sub-agents preserve your context window (50-100x savings) and ensure proper source citation.

The Iron Law

NO DIRECT RESEARCH. ALWAYS USE SUB-AGENTS.

When to Use

Use sub-agent for research when:

• Looking up library/framework documentation
• Researching best practices or patterns
• Investigating how a technology works
• Explaining core concepts or comparing technologies (e.g., "What is X?", "X vs Y")
• Finding API references or syntax
• Searching for error messages or solutions in external sources
• Any information gathering task

Do NOT research directly:

• Not for "quick questions"
• Not for "simple lookups"
• Not when "time is tight"
• Not because "spawning sub-agent seems like overhead"

What Research Is NOT

Research ≠ Reading existing codebase to verify patterns Research ≠ Checking current implementation Research ≠ Reviewing code you just wrote

You CAN read existing code without sub-agent to:

• Verify a pattern matches what you ALREADY researched (via sub-agent)
• After completing research, check if implementation follows researched pattern
• Understand current implementation structure
• Locate where errors occur during debugging

You CANNOT read existing code to:

• Infer how a technology works
• Guess at best practices
• Avoid looking up official documentation
• Research BEFORE verification (must research first, THEN verify)
• Understand WHY a framework behaves a certain way (requires research)

Research Sources (Strict Failure Model)

1. Context7 MCP

For: Known libraries/frameworks (Payload CMS, Next.js, React, PostgreSQL, etc.)

Sub-agent must:
1. Use mcp__context7__resolve-library-id first
2. Use mcp__context7__get-library-docs with resolved ID
3. If authentication fails → STOP and report error
4. If library not found → STOP and report error

Never: Automatically fall back to WebSearch on failure

2. WebSearch

For: Technologies NOT in Context7, or when explicitly requested

Never: As automatic fallback when Context7 fails

3. WebFetch

For: Specific URLs from WebSearch results OR URLs provided by user

Never: Random documentation sites without verification

Strict Failure Protocol

When research fails:

Context7 auth error → STOP, report to user
Context7 library not found → STOP, report to user
WebFetch 429 rate limit → STOP, report to user
WebSearch no results → STOP, report to user

NEVER:

• Try next source automatically
• Make assumptions about the answer
• Infer from existing code
• Guess based on similar technologies

Sub-agent Instructions Template

Research [specific question] for [technology].

Sources to try:
1. [Context7 MCP / WebSearch / WebFetch with URL]

Requirements:
- If source fails (auth error, 404, rate limit), STOP and return the exact error
- Do NOT try alternative sources
- Do NOT make assumptions or inferences
- Do NOT look at existing code to guess

Return:
- Direct answer to the question
- Code examples if available
- Explicit source citation: "Source: [Context7 MCP - Library Name]" or "Source: [URL]"

If you cannot get the information, return:
"FAILED: [exact error message]"

Common Rationalizations (All Wrong)

| Excuse | Reality | |--------|---------| | "Quick question, no sub-agent overhead" | Sub-agents save 50-100x context. Always worth it. | | "Context7 faster than sub-agent" | Seconds faster, thousands of tokens wasted. Use sub-agent. | | "Simple lookup, seems like overkill" | ALL research uses sub-agents. No complexity threshold. | | "Time pressure, need answer now" | Sub-agents ARE faster - they preserve your context. | | "I probably know this already" | Assumptions are wrong. Research official docs. | | "Let me check existing code first" | Only valid to VERIFY after research, not INSTEAD of research. | | "This is straightforward enough" | Straightforward = perfect for sub-agent. Do it. |

Red Flags - STOP

If you're thinking ANY of these thoughts, STOP and use a sub-agent:

• "Let me just quickly search..."
• "I can look this up faster myself..."
• "This is too simple for a sub-agent..."
• "No time to spawn a sub-agent..."
• "I'll just check the existing code..."
• "Based on similar technologies, I assume..."

Example: Correct Research Flow

User asks: "How do I handle role-based access in Payload CMS?"

❌ WRONG:
- Search Context7 yourself
- Look at existing auth code to guess
- Make assumptions based on general CMS knowledge

✅ CORRECT:
1. Dispatch sub-agent with instructions:
   "Research role-based access control in Payload CMS.

   Sources: Context7 MCP - resolve 'payload cms' then get docs on 'access control roles'

   Requirements:
   - If Context7 fails, return the error and STOP
   - Must cite source explicitly
   - Include code examples"

2. Wait for sub-agent report
3. If sub-agent reports failure, report to user
4. If sub-agent succeeds, summarize findings with source citation

Source Citation Requirements

Every research result MUST include explicit source:

✅ GOOD:
"Source: Context7 MCP - Payload CMS documentation (Library ID: /payloadcms/payload)"

✅ GOOD:
"Source: https://nextjs.org/docs/app/building-your-application/optimizing/images"

❌ BAD:
"Based on the documentation..."
"According to best practices..."
"The official docs say..."

Common Knowledge Exceptions

These do NOT require sub-agent:

• Universal programming fundamentals (variables, functions, loops, conditionals, arrays)
• Basic shell commands (cd, ls, mkdir, git status)
• Universal package manager verbs (install, update, init)

These DO require sub-agent:

• Framework/library-specific concepts (hooks, components, directives, middleware)
• Technology comparisons ("Server Components vs Client Components", "React vs Vue")
• Command flags or options (pnpm install --frozen-lockfile)
• Technology-specific behavior (how pnpm differs from npm)
• Version-specific features or changes
• Configuration options or best practices

Rule: If it's documented in a library's/framework's official docs, it requires research.

When in doubt: Use sub-agent. Common knowledge threshold is VERY narrow.

Debugging vs Research

Debugging without sub-agent:

• Reading code to locate error source
• Checking variable values and execution flow
• Tracing through current codebase logic

Debugging that requires sub-agent:

• Searching external sources for error messages
• Understanding WHY a framework/library behaves unexpectedly
• Looking up proper usage patterns to fix the bug
• Researching how something SHOULD work

Rule: If debugging reveals you don't understand HOW something should work, switch to research with sub-agent.

Meta-Research Questions

Questions about methodology (no sub-agent needed):

• "Which research tool should I use for X?"
• "What's the difference between Context7 and WebSearch?"

Questions requiring verification (need sub-agent):

• "Is X available in Context7?" (requires checking)
• "Does Context7 have documentation for X?" (requires attempting resolution)

The Bottom Line

Research = Sub-agent. Every single time.

Only exception: Narrow common knowledge threshold. Sub-agents preserve context and ensure quality. Use them.