# Agent brief

A template for handing a bounded task to a subagent that runs on its own and
comes back with one report. Skills are how I do X. Agents are go do X and
report back. This is the brief that makes the handoff work.

The brief has to be complete, because the agent is stateless: it gets this
document, does the work, returns one result, and there is no back-and-forth.
Anything you would have answered mid-task has to be answered here, up front.

---

## When to dispatch an agent instead of doing it in the main thread

| Situation | Do it in the thread | Dispatch an agent |
| --- | --- | --- |
| The task needs a dozen or more file reads whose contents you do not need to see yourself | | yes |
| The task is a question ("where is this handled and why") with a short answer | | yes |
| The task is independent of other work in flight and could run in parallel | | yes |
| The task needs your judgment at several points along the way | yes | |
| The task changes files you are also editing | yes | |
| The task is one step, one file, one look | yes | |

The tell is context. If the work would flood the main conversation with
material you only need the conclusion of, that is an agent. Dispatching an
exploration agent for a big question keeps the thread readable and keeps the
model's attention on the decision rather than the search.

---

## The template

Copy from here down. Fill every field. A blank field is a guess the agent
will make for you.

```
# Brief: <one-line task name>

## Objective
<One sentence. What is true when this is done. Not "look into", but "return X".>

## Scope
In scope:
- <directory, file set, system, or question boundary>
Out of scope:
- <the adjacent thing this must not touch or answer>

## Inputs
- <file paths, links, sample data, prior decisions the agent needs>
- <where to find anything it will need to verify a claim>

## Constraints
- Access: <read-only | may edit these paths only | may run these commands>
- Do not: <the specific action that would be costly if taken, stated plainly>
- Verify before asserting: <what counts as a source for a claim in this task>

## Output contract
Return exactly this shape:
1. <Answer or result, first, in one paragraph>
2. <Evidence: file paths with line numbers, query results, or links>
3. <What was not found or could not be verified, stated as such>
4. <Open questions, if any, as a list, not folded into prose>

## Done criteria
- [ ] <a check the agent can apply to its own report before returning>
- [ ] <another, mechanical, pass or fail>

## Stop conditions
Stop and return early, reporting why, if:
- <a precondition turns out to be false>
- <the task turns out to need a decision only I can make>
```

---

## Notes on each field

**Objective.** One sentence, phrased as the end state. "Return the list of
call sites for the pricing function and which of them handle a null rate" is
an objective. "Investigate pricing" is a wish.

**Scope.** The out-of-scope list is the more important half. Agents drift
toward the interesting adjacent problem. Name it and rule it out.

**Inputs.** Everything the agent would otherwise have to discover. If you know
where the answer probably lives, say so; the agent should confirm, not
rediscover.

**Constraints.** Read-only is the default for exploration. If the agent may
edit, list the exact paths. If an action is irreversible or outward-facing
(publishing, sending, deleting), it does not belong in an agent brief at all;
that step stays with a person.

**Output contract.** Fix the shape so the report can be consumed without
being reformatted. Answer first, evidence second, gaps third. The gaps
section is what makes the report trustworthy: an agent that reports "not
found" is more useful than one that fills the space.

**Done criteria.** Written as checks the agent runs on its own output. "Every
claimed call site cites a file and line" is a check. "Thorough" is not.

**Stop conditions.** The agent should return early rather than push through a
false premise. A short report saying "the function you named does not exist;
the nearest match is Y" is a successful run.

---

## Three traits worth preserving

- **Stateless and scoped.** Each invocation gets a full brief and returns one
  result. If you find yourself wanting a conversation with the agent, the
  brief was incomplete. Fix the brief.
- **Parallelizable.** Independent read-only agents can run side by side.
  Three questions, three agents, one review.
- **Specialized.** A roster of agents tuned to a domain (codebase
  exploration, data queries, documentation search, publishing) beats one
  general agent, because the brief for a specialist is shorter and the report
  is more predictable.