# Subagents: example scenario

A saved, read-only reviewer subagent checks each change in ticket-service against the issue's acceptance criteria and the team conventions in its own context.

Source: https://ai-sw-factory.mellicci.dev/fundamentals/subagents/example-scenario

## Scenario

In `ticket-service`, the agent that implements an issue also "reviews" it. It carries its own assumptions into the review, and the review fills the main context with diffs and file dumps. Reviews miss unmet acceptance criteria and let route changes through without tests.

This page shows one way to fix that: a saved specialist named `reviewer` that works in its own context, can only read, and returns a verdict.

## Before → after

| | Before | After |
|---|---|---|
| Independence | The author reviews its own work, with its own assumptions | A fresh context sees only the brief, the diff and the issue |
| Context size | Diffs and file dumps stay in the main context | The main context grows by the verdict only |
| Quality | Unmet criteria and untested routes slip through | Each criterion gets pass or fail; conventions are checked every time |
| Risk | Review and edits happen in one loop | The reviewer has no edit tools, so it cannot change code |

## Design

**Diagram:** The main agent sends a brief to the reviewer, which works in its own read-only context and returns a verdict.

- Main agent — implements the issue
- → brief with issue number
- Reviewer · own context (read-only tools, optional other model):
  - Reviewer — diff, issue, conventions
- → verdict
- Main agent — fixes the findings

The definition is a saved file. This is generic; file format, field names and location differ per agent.

```text
# generic subagent definition
name:         reviewer
description:  Reviews the current change in ticket-service against the
              issue's acceptance criteria and the team conventions. Use
              after implementing an issue, before opening a pull request.
              Read-only.
tools:        read and search files, git diff (read-only),
              read the issue (GitHub MCP server, where allowed)
model:        optional, a different model than the main agent
instructions: |
  Read `git diff main...HEAD` and the issue.
  Check each acceptance criterion.
  Check conventions: every route change has a test in test/;
  nothing in src/db/migrations/ is hand-edited.
  Return a verdict: pass or fail per criterion, then findings with file:line.
  Never edit files.
```

The issue comes from the [MCP server](https://ai-sw-factory.mellicci.dev/fundamentals/mcp) set up in the [MCP scenario](https://ai-sw-factory.mellicci.dev/fundamentals/mcp/example-scenario), where your agent allows it. A different model gives a second opinion, where the agent supports choosing one.

## What happens at runtime

<steps>

<step title="Match">

You finish issue #42. The main agent sees that the task matches the `reviewer` description, or you say "have the reviewer check this change".

</step>

<step title="Brief">

The main agent writes a short brief that names issue #42 and the branch. The reviewer does not see the conversation.

</step>

<step title="Review in isolation">

The reviewer runs `git diff main...HEAD`, reads the issue, and checks each criterion and convention. Its reads stay in its own context.

</step>

<step title="Verdict">

It returns pass or fail per criterion and findings with file:line, then stops.

</step>

<step title="Fix">

The reviewer runs in the foreground, so the main agent waits, then fixes the findings itself.

</step>

</steps>

Some agents can run a subagent in the background, or several reviewers in parallel, each with a different focus.

## What can go wrong

| Failure | How you notice | What to do |
|---|---|---|
| The reviewer rubber-stamps: same model, same blind spots | Verdicts are all "pass" while bugs reach the pull request | Use another model for the reviewer, or sharpen the criteria in its instructions |
| The verdict is too long | The main context fills with review text again | Limit the verdict format: one line per criterion, findings as file:line |
| The reviewer got edit tools by accident | Files change during a review, or the diff differs after it | Check the tool list; allow only read, search and `git diff` |
| An extra loop costs time and tokens | Each change takes noticeably longer | Review before the pull request, not after every edit; consider a cheaper model |
| The brief lacks the issue number | The reviewer checks against nothing, or guesses the issue | Put the issue number in the brief, and say so in the instructions |