Output Formats and Obstacle Reporting
The Single Most Important Improvement
If you do only one thing to make a subagent reliable, define an output format in its system prompt. This is the single highest-impact change you can make. It solves two problems at once that plague unconfigured subagents.
| Without an output format | With a defined output format |
|---|---|
| Subagent doesn't know when it's 'done' | Each filled-in section is a natural stopping point |
| Tends to over-research and run long | Stops once every section is complete |
| Returns unstructured prose the main thread must parse | Returns predictable structure the main thread can use |
A defined output format gives the subagent a checklist — it knows it's finished when every section is filled in.
Why does this work? Without a defined output, subagents struggle to decide when enough work has been done and tend to run much longer than necessary. An output format converts an open-ended task into a finite checklist with clear stopping points.
A Structured Output Format in Practice
Here's a battle-tested output format for a code-review subagent. Notice how each section is a concrete deliverable — the subagent works through them and knows it can stop once all are filled in.
Provide your review in a structured format:
1. Summary: Brief overview of what you reviewed and overall assessment
2. Critical Issues: Security vulnerabilities, data integrity risks,
or logic errors that must be fixed immediately
3. Major Issues: Quality problems, architecture misalignment, or
significant performance concerns
4. Minor Issues: Style inconsistencies, documentation gaps, or
minor optimizations
5. Recommendations: Suggestions for improvement, refactoring
opportunities, or best practices to apply
6. Approval Status: Clear statement of whether the code is ready
to merge/deploy or requires changesWhy a final 'status' section helps
Ending with an explicit decision section (Approval Status) forces the subagent to commit to a conclusion rather than trailing off in vague observations. The main thread gets an actionable verdict, not just notes.
Reporting Obstacles
When a subagent discovers a workaround during its work — solving a dependency issue, finding that a command needs particular flags — those details must appear in its summary. If they don't, the main thread has to rediscover the same solutions on its own, wasting time and tokens. The fix is to explicitly ask for them by adding an 'Obstacles Encountered' section to the output format.
7. Obstacles Encountered: Report any obstacles encountered during the
review process. This can be: setup issues, workarounds discovered, or
environment quirks. Report commands that needed a special flag or
configuration. Report dependencies or imports that caused problems.- •Setup issues or environment quirks the subagent had to navigate.
- •Workarounds it discovered to get unstuck.
- •Commands that needed special flags or configuration.
- •Dependencies or imports that caused problems.
Why This Saves the Whole Session
Remember context isolation: when the subagent's conversation is discarded, every lesson it learned vanishes unless it's in the summary. Obstacle reporting is how you preserve that hard-won knowledge across the isolation boundary, so the main thread inherits the solutions instead of hitting the same walls.
Output format = stopping points + structure + preserved knowledge
A good output format does three things: tells the subagent when it's done (stopping points), returns information the main thread can act on (structure), and — with an Obstacles section — carries discovered workarounds back across the isolation boundary. This is the design pattern that most separates reliable subagents from flaky ones.
Next
Descriptions shape the input; output formats shape the finish. The third design pillar is constraint: limiting which tools a subagent can touch.
Key Takeaways
- ✓Defining an output format in the system prompt is the single most important improvement to a subagent's reliability.
- ✓It creates natural stopping points (the subagent is done when every section is filled) and prevents over-long, open-ended runs.
- ✓A structured format also returns predictable, actionable information instead of unstructured prose the main thread must parse.
- ✓Ending with an explicit decision section (e.g. Approval Status) forces the subagent to commit to a conclusion.
- ✓Add an 'Obstacles Encountered' section so workarounds, env quirks, special flags, and dependency issues are surfaced — not rediscovered.
- ✓Because the subagent's conversation is discarded, obstacle reporting is how hard-won knowledge survives the context-isolation boundary.
Check Your Understanding
Test what you learned in this lesson.
Q1.What is the single most important improvement you can make to a subagent's reliability?
Q2.Why does a defined output format stop a subagent from running too long?
Q3.What is the purpose of an 'Obstacles Encountered' section in the output format?
Q4.Why is obstacle reporting especially important given context isolation?
Practice This Lesson