Reviewing a Subagent Instruction Like a Code Diff

Before you can diff an instruction, the artifact has to be separable. Split it into four parts and version them as a unit:

1. The role and intent line. One or two sentences on what this subagent owns and what it must never do.
2. The input contract. Exactly which fields the orchestrator supplies, with types and examples.
3. The tool list. Named tools and the conditions under which each may be called. A subagent locked to a narrow tool set selects better and cannot wander; least-privilege boundaries are enforced by configuration rather than by hoping the model behaves (Claude Code subagent guide).
4. The output schema. The exact structure returned to the parent, ideally machine-validated.

That four-part split mirrors a useful academic abstraction: any agent can be modeled as a tuple of instruction, context, tools, and model, and an orchestrator concretizes that tuple at each step (AOrchestra, arXiv). If your review only covers part one, you are reviewing a quarter of the change surface.

The reason to insist on a schema is that the parent agent's job is to combine results, not to parse prose. Structured Outputs constrain the model to generate responses that adhere to a supplied JSON Schema, so a required key cannot be silently omitted and an invalid enum value cannot be hallucinated (OpenAI structured outputs). Frameworks implement the same idea in their own way, validating arguments against a schema before returning a typed object (Strands Agents). Whatever the mechanism, the schema belongs in the diff.

A worked example of size: a handoff that returns five required fields, calls three tools, and passes the parent one or two reference identifiers is small enough to review in minutes. The same handoff that returns free-form prose and calls a general-purpose search tool is not reviewable at all, because the reviewer cannot tell what "correct" output looks like.

The reviewing rule that does the most work is boring: a single review carries a single intent. If the pull request says "tighten the refusal behavior and also fix the date format," split it. Two intents mean two tests, two rollbacks, and no clean answer when something breaks.

Write the intent as a testable sentence before you touch the text. Bad: "improve the subagent prompt." Good: "when the retrieval tool returns zero documents, the subagent must return status insufficient_context instead of drafting an answer." The second version tells the reviewer exactly which case in the matrix must change behavior, and it tells the approver what evidence to look for.

For the diff itself, keep the instruction in a plain text or Markdown file under version control, and review the rendered diff of that file, not a screenshot of a prompt editor. An agent definition is often a single file holding the name, description, tool list, and system prompt, which makes line-level diffs natural (Prompt Engineering). Then state the blast radius in the description: which orchestrator call sites use this subagent, which downstream consumers read its output, and whether the change is additive (new optional field) or breaking (renamed field, removed tool).

A short template keeps this consistent:

intent: subagent must refuse when retrieval returns zero docs
diff:
  - instruction: add refusal clause, remove "always answer" sentence
  - tools: unchanged
  - schema: add optional status field, no required-field changes
blast radius: 3 call sites, one downstream consumer reads summary only
evidence: matrix run 2024-xx-xx, all 4 cases, traces linked
rollback: tag subagent-researcher-1.3.0

The last two lines are the ones reviewers skip and approvers should demand.

Unit tests on prompt text do not exist. What you can test is the handoff end to end: orchestrator in, final combined answer out, with assertions on what crossed the boundary. Four cases cover most of the realistic failure surface.

The design of these cases comes straight from orchestrator-worker mechanics. Seamless handoffs and error handling are named as core challenges of the pattern, alongside context continuity and concurrency (Arize). A matrix that only tests the happy path tests the one thing that already worked.

Two numbers help you size the timeout case honestly. A subagents architecture adds at least one extra model call per interaction because results must flow back through the main agent, which costs latency and tokens (LangChain). And in a four-agent sequential pipeline, one published analysis measured roughly 950 ms of coordination overhead against about 500 ms of actual processing (Beam AI). Your timeout has to sit above the sum, not above the average. Measure it from traces rather than guessing, because the orchestrator makes its own calls for decomposition and aggregation on top of every worker call.

Record every matrix run against the version tag, with a link to the trace for each case. Observability is not optional here; if you cannot see the delegation prompt and the returned payload in a trace, you cannot review a change to either. Logging when a connected agent is invoked and what it did, with identifiers that link parent and child sessions, is the stated practice for exactly this reason (Microsoft Learn).

Version the instruction the way you version code, and tie the tag to the evidence.

• Tag format. Use a readable string that encodes the artifact and a monotonic version, for example subagent-researcher-1.3.0, and put the same string in the changelog and in the runtime configuration.
• Changelog entries. One line per release: intent sentence, date, matrix result, approver. This is the audit trail a reviewer reads six months later.
• Rollback tag. Every release records the previous tag it can revert to. Rollback must be a configuration change, not a text edit under pressure.
• Pinned environments. Test and production run the same pinned version so the matrix evidence describes what is actually deployed.

This is the same discipline IT change management applies to infrastructure: identify who raised the change, the reason, the expected return, the risks, the resources, the responsible owner, and the relationship to other changes in flight (SolarWinds). You can borrow the shape without the ticket system. A single file per release in the repository, reviewed alongside the diff, covers all seven questions at the scale a prompt change deserves.

One subtlety: version the instruction and the model setting together but keep them separately visible. Teams that swap a model in an emergency while editing the prompt lose the ability to attribute a behavior change to either. If you route many model families through one API, keeping the model identifier as an explicit, reviewed field in the same artifact is the cheap fix; Quanta Inference exposes text, image, video, audio and embedding models behind one OpenAI-compatible key, which makes the model field a plain configuration value you can pin and diff (https://quantaintelligence.ai/inference).

Name one approver per instruction. For a subagent that reads and writes nothing sensitive, that can be the orchestrator's owner. For one with write access, database tools, or customer-facing output, it should be someone outside the authoring team.

The approver's job is narrow and mechanical. Check four things:

1. The stated intent matches the diff, and the diff contains nothing unrelated.
2. The matrix ran on this exact version, all four cases, with traces attached.
3. The schema change is additive, or every downstream consumer is updated in the same release.
4. The previous tag is recorded and rollback has been exercised at least once since the last breaking change.

Notice that none of these require the approver to judge whether the prompt is well written. That is the author's craft. The approver judges whether the change is controlled, which is a different and more checkable question.

Escalate the sign-off when the subagent crosses a trust boundary. Microsoft's guidance is explicit that a connected agent may have access the parent does not, so a call that could delete records should be subject to the same checks or consent as any other powerful action (Microsoft Learn). In the review, that becomes a hard rule: any tool added to a subagent's list is reviewed by whoever owns the system behind that tool, not just by the prompt author.

Most bad prompt changes pass review because the review looked at the wrong thing. These are the recurring holes.

The diff covers the prose but not the tools. Someone removes a sentence and quietly drops a tool from the allowed list in a separate configuration file. The matrix should have caught it; it did not, because the test ran against the old configuration. Fix: pin configuration to the tag.

The normal case is the only case. Teams write one good example, confirm it works, and ship. The four failure cases are where handoff bugs live. This is not unique to prompts: in multi-agent orchestration generally, error handling and seamless handoffs are named among the hardest problems, and coordination overhead grows with every component you add (Arize).

The instruction drifts from the architecture. A subagent written for a single worker gets reused as one of several parallel workers, and the instruction still says "you are the only source of the answer." When you separate agents, the parent must be the only one that responds to the user and must combine child findings; leaving that ambiguous lets subagents reply on their own (Microsoft Learn). Any change to how many agents sit in the flow is an instruction change and belongs in the diff.

Nobody owns the output schema. The subagent team edits the schema to add a field; the consumer never hears. Assign the schema to the consumer's team in the ownership table and require their approval on breaking changes.

Rollback has never been run. The tag exists; the process was never exercised. Test a rollback quarterly the same way you test a restore, and record it in the changelog.

For teams running several subagents across business units, the review discipline is also the on-ramp to delegation: it produces the evidence a specialist needs to take over a handoff, which is the premise behind Quanta Experts, where each expert reads your context and returns finished deliverables rather than advice (https://quantaintelligence.ai/agents). The checklist above is what makes that handover safe.

Run this before the diff goes to the approver. If any line is a no, the change is not ready.

• Intent is one testable sentence, and the diff contains nothing outside it.
• Instruction text, tool list, and output schema are all visible in the same review.
• The four-case matrix ran on this exact version; traces are linked.
• Timeout budget was checked against measured latency from traces, not estimated.
• Every downstream consumer of the output schema has reviewed breaking changes.
• The previous tag is recorded, and a rollback was exercised since the last breaking change.
• A named approver has read the evidence, not the description.

Keep the checklist in the repository next to the instruction file so it moves with the artifact. Reviewers who see it every time stop treating prompt edits as informal.