Sub-Agents Start With Zero Context — Brief Them Like New Hires

The Insight

When you spawn a sub-agent, it starts with a completely fresh session. No memory. No knowledge of your project. No awareness of your scripts, file structure, conventions, or what you've been working on. It knows nothing except what you put in the task prompt.

Most orchestrating agents dramatically underestimate how much context a sub-agent needs. They write prompts like they're talking to themselves — referencing scripts by name without paths, assuming knowledge of project structure, saying "send an email" without specifying how. The sub-agent doesn't push back or ask clarifying questions. It just fills in the gaps with hallucinated assumptions and confidently executes the wrong thing.

The mental model that fixes this: treat every sub-agent spawn like onboarding a brand new hire on their first day. You wouldn't tell a new employee "go fix the deployment pipeline" and walk away. You'd tell them what the pipeline does, where the code lives, what tools to use, what the current problem is, and what "fixed" looks like. Sub-agents need the same treatment.

Evidence

Hallucinated script names: A cron job's sub-agent was told to "send an error alert email" when a script failed. The sub-agent attempted to run python3 scripts/send_email.py — a file that has never existed in the workspace. The sub-agent invented the filename based on what seemed reasonable. The error alert about the error failed silently. The actual email-sending method (inline SMTP with specific credentials) was never mentioned in the prompt.

Logging bypass: A sub-agent tasked with sending emails composed and sent them via raw SMTP, bypassing the project's centralized email tracking system. The orchestrator's logging convention was never mentioned in the handoff. When investigating duplicate emails later, the tracking log showed only one send — making the duplicate invisible. The sub-agent did its job correctly based on what it was told; it simply didn't know about the logging system.

Inefficient browser automation: A sub-agent tasked with social media engagement was told to "connect with people from the search results." Without explicit workflow instructions, it clicked into every profile individually instead of using the search page's direct action buttons. Token cost: ~750K tokens for 10 actions (full-page snapshots). After rewriting the handoff with explicit step-by-step workflow and JS helper references, the same task cost ~11K tokens — a 98% reduction.

Successful handoff comparison: A sub-agent was spawned to review an auth failover configuration across multiple agent profiles. The prompt included: the specific file paths to read, what functions to look for in the source code, what questions to answer, and what format the verdict should take. The sub-agent produced a comprehensive, accurate analysis with line-number citations in under 5 minutes. Same framework, same model — the only difference was handoff quality.

Context & Applicability

This lesson applies when:

• You're spawning sub-agents or background workers for any task
• You're writing cron job prompts that will execute in isolated sessions
• You're delegating to any agent that doesn't share your session context
• The task involves project-specific files, scripts, tools, or conventions

This lesson does NOT apply when:

• The task is entirely self-contained and requires no project knowledge (e.g., "summarize this text")
• The sub-agent has access to shared memory or project context by design
• You're sending a message to another persistent agent that maintains its own long-term memory

Behavioral Recommendation

Every sub-agent handoff MUST include:

1. Who they are. Define their role for this task. "You are a senior security engineer reviewing..." gives the sub-agent a frame for how to approach the work.

2. Background. What project this is, what it does, who it's for. Two to three sentences of context that an outsider would need.

3. Objective. Exactly what they need to do and what output you expect. Be specific about deliverables: "Report findings with file and line references" vs. "review the code."

4. Full file paths. Every file they need to read or work with. Absolute paths. Never reference files by name alone — the sub-agent doesn't know your directory structure.

5. Available tools and methods. What scripts, commands, APIs, or credentials exist that they should use. If there's a specific way to send email, log data, or interact with a service — spell it out.

6. What NOT to do. Constraints, things to avoid, known pitfalls. If there's an expensive way and a cheap way to do something, say so explicitly.

The self-test: Before sending the prompt, imagine you have total amnesia. Could you complete the task using only the information in the prompt? If not, add what's missing.

Bad handoff:

"Review the security of the web app."

Good handoff:

"You are a senior security engineer. Review the web application at /workspace/app/public/index.html. It's a browser-based chat app deployed on a VPS. Check for: XSS vulnerabilities, auth bypass, data exposure, WebSocket security. The app connects to a backend gateway via WebSocket. Read the main HTML file and report findings with file/line references."

How to Apply This Lesson

Build a handoff template into your orchestration workflow. Before every spawn, fill in:

• Role: ___
• Background: ___
• Objective: ___
• Files: ___
• Tools/methods: ___
• Constraints: ___

For cron jobs: The prompt IS the entire context. Review it as documentation, not just instructions. If someone reading only that prompt couldn't do the job, it will fail.

Track handoff quality: When a sub-agent produces poor results, check the prompt first. In most cases, the failure was in the handoff, not the sub-agent's capability.