guide orchestrator subtask context isolation

docs/subtask.md

@@ -5,7 +5,8 @@ one specific piece of work. The worker runs as an orchestrator in a real child
 session, completes the requested task, and sends a structured summary back to
 the original conversation.
 
-Use it when you want to offload a focused task without losing the main thread.
+Use it when a bounded, context-heavy task only needs to return a compact result
+to the main thread.
 
 ## Usage
 

src/agents/orchestrator.ts

@@ -173,6 +173,25 @@ ${enabledParallelExamples}
 
 Balance: respect dependencies, avoid parallelizing what must be sequential.
 
+### Context Isolation
+If no specialist delegation is needed, consider `subtask` before doing
+context-heavy work directly.
+
+Ask whether the parent context needs the details or only the result. Use
+`subtask` when the work is bounded, context-heavy, and the parent only needs a
+compact outcome.
+
+Use `subtask` for focused investigation, bounded analysis, cleanup, or
+verification across files/logs/messages.
+
+Do not use `subtask` for tiny tasks, open-ended work, interactive decisions,
+work better handled by a named specialist, or cases where the parent must reason
+over the details.
+
+When calling `subtask`, give a self-contained prompt with objective,
+constraints, relevant context, deliverable, and validation. Pass only clearly
+relevant files. Wait for the summary, then integrate and verify it.
+
 ### OpenCode subagent execution model
 - A delegated specialist runs in a separate child session.
 - Delegation is blocking for the parent at that point: send work out, then continue that line after results return.