Critique underbriefed subagent prompt
What you'll learn
Subagents have no memory of the parent conversation. Write the brief as if explaining to a teammate who just walked in: goal, context, constraints, expected output.
- Subagents have no parent-conversation memory. Brief is all they have.
- Brief = goal + relevant context + constraints + expected output shape.
- Smell phrases: 'based on the above', 'as discussed', 'continue from where we left off'.
Subagents start with no memory of the parent conversation. The brief you send is *all* the context they have. The single most common subagent failure is **underbriefing** — sending a vague prompt like 'based on the analysis above, write the code' or 'continue from where we left off' and expecting the subagent to fill in the implicit context. It can't; there is no 'above' or 'we' for it.
A well-formed subagent brief names: (1) the **goal** in one sentence, (2) the **relevant context** the subagent needs (file paths, existing decisions, constraints), (3) **explicit constraints** (what to avoid, what's out of scope), and (4) the **expected output shape** (return a summary, return a diff, return a JSON record). Each of these has to be in the brief because the subagent has no other source.
The smell list: phrases like 'based on the above', 'as discussed', 'continue from where we left off', 'follow our usual style', 'apply the standard pattern' — every one of these references implicit context the subagent doesn't have. Critiquing a subagent prompt means scanning for these phrases and forcing each one to be made explicit.
The fix: write the brief as if the subagent is a smart colleague who just walked into the room. They haven't seen the conversation; they don't know the goal; they need the context, the goal, the constraints, and the output shape spelled out. If the brief is shorter than what you'd write as a Slack message to a teammate, it's underbriefed.
Key points
- Subagents have no parent-conversation memory. Brief is all they have.
- Brief = goal + relevant context + constraints + expected output shape.
- Smell phrases: 'based on the above', 'as discussed', 'continue from where we left off'.
- Fix: write as if briefing a smart colleague who just walked in.
Examples
'Based on the analysis above, write the implementation.' Subagent has no analysis to read; it'll guess plausibly and return plausible nonsense.
'Implement function `parseInvoiceLine(line: str) -> Invoice` per the spec at docs/invoice_format.md. Constraints: no external dependencies, raise ValueError on malformed lines. Return: the function definition only, no surrounding boilerplate. Existing test cases in tests/test_invoice.py — your implementation should pass them.'
Pitfalls
- Treating the parent context as 'the subagent will see this'. It won't.
- Using pronouns and references that depend on parent-conversation context.
- Not naming the expected output shape. Subagent guesses; parent receives wrong shape.
- Skipping constraints because they 'feel obvious'. Without the parent context, nothing is obvious.
Source notes: 00-academy-basics/notes/08-subagents.md
Ask Claude
Build a prompt with this lesson + your question, copy it, and open the Claude Project in a new tab.