Stop Hiring One Super-Agent: Divide Research by Evidence Boundary

Part 2 of “Designing Coding Agents That Earn Write Access.”

A drafting agent of mine once told me an API had landed in version 0.1.1.

It had not. The changelog said the API shipped in 0.1.0+1, and that 0.1.1 was a release that only refreshed a dataset.

The interesting part is where 0.1.1 came from, because it did not come from anywhere. The agent had read a curated internal note whose version field was a stale placeholder, and it had read the current state of the code. Neither source said 0.1.1. The number was produced in the seam between them—one source supplying an approximate shape, the other supplying enough live detail to make the shape look confirmed.

There is no line in either source I can point to and call wrong. That is exactly what made it hard to catch, and it is why the fix could not be “read more carefully.” The fix was a rule about provenance: a “landed in version X” claim must trace to the changelog specifically, because curated prose plus current code is precisely the combination that manufactured the error.

I was thinking about that failure when I sat down with three research-agent specifications.

One inspected a repository. One checked Flutter and Dart documentation. One searched a curated collection of internal implementation patterns.

The lazy model was obvious: call all of them “researcher,” pour their instructions into one enormous prompt, and let a single agent sort it out.

I like deleting unnecessary abstractions, so this was dangerously attractive (one file! one name! one future headache wearing a tidy hat!).

But the three roles were not separated by topic. They were separated by what counted as evidence.

That difference turned out to be the entire design.

One Job Title, Three Different Questions

“Research this feature” sounds like one task. It usually hides several questions.

The first question is local:

What does this repository actually do today?

The codebase researcher answers by inspecting project structure, state management, data-layer patterns, similar implementations, tests, and repository instructions. Its useful output contains file paths and observed conventions. It should not tell you what Flutter recommends in general when the repository already has a different established pattern.

The second question is external:

What do the platform and package sources currently promise?

The documentation researcher checks SDK constraints, resolved package versions, deprecations, breaking changes, migration notes, official documentation, and—when documentation is insufficient—source code and tests. Its job is to distinguish current platform truth from whatever the project happened to believe last year.

The third question is historical:

What durable internal precedent already exists for this kind of work?

The patterns researcher starts from a curated knowledge base, extracts only the guidance relevant to the task, and opens deeper references only when necessary. Its purpose is not broad discovery. It is fast retrieval of prior engineering decisions.

Local reality, external truth, and internal precedent can agree. They can also disagree spectacularly.

That is precisely why I do not want one general researcher blending them into a smooth paragraph. Smooth paragraphs are lovely until you need to know which sentence came from the repository and which one came from a remembered pattern (ask me how I learned to distrust smooth paragraphs).

A Role Should Own an Evidence Boundary

The usual way to specialize an agent is by technology:

Flutter agent
React agent
Database agent
Security agent

That can be useful, but it does not solve provenance. A “Flutter agent” may still mix local code, official documentation, package README files, cached knowledge, and personal preference in one answer.

An evidence-boundary design asks different questions:

Role: Codebase researcher
Primary evidence: files in the target repository
Question: what conventions and implementations exist here?
Output: paths, patterns, analogous code, and gaps

Role: Documentation researcher
Primary evidence: current SDK, package, and official sources
Question: what behavior and compatibility are supported now?
Output: version-aware findings, risks, and references

Role: Patterns researcher
Primary evidence: curated internal knowledge
Question: what prior guidance applies to this task?
Output: relevant patterns, principles, and anti-patterns

These are not the literal agent files. They are the compact design I derived from them.

The boundary makes disagreement useful. If the codebase researcher says “this project uses pattern A” while the documentation researcher says “pattern A is deprecated,” the conflict is visible. The implementation plan can then decide whether to preserve local convention, migrate it, or narrow the task.

I got a second demonstration of this while checking a claim about React Native’s NativeEventEmitter. My curated note said the New Architecture warnings fire on every listener registration. The library’s own changelog said the same thing.

Two sources agreeing felt like corroboration, and it was not. The note cites that changelog as its source — the agreement was one claim copied downstream, wearing a second hat. Opening the framework source settled it: the two console.warn calls live inside the NativeEventEmitter constructor, not inside addListener. The warning fires once per emitter constructed, not once per listener registered.

Agreement between secondary sources is not corroboration. It is often just a shared ancestor. The only reason that error was catchable is that “what my notes say” and “what the platform source says” had never been merged into one undifferentiated pile of knowledge.

Without that separation, the agent may quietly average the two sources into something nobody actually said. Language models are excellent mixers. Unfortunately, evidence is not a cocktail.

Durable Role, Temporary Task

While organizing these agent specifications, I ran into a second modeling problem: what deserves to become a reusable agent at all?

The answer I settled on was simple.

A durable named role deserves a stable identity when future tasks need to invoke it, compare it, or reason about its responsibility. A temporary procedure can remain a prompt, command, or task note. A taxonomy belongs above the individual roles only when several agents need a shared grouping rule.

In knowledge-base terms, I kept the original specification as source evidence, represented the reusable role as its own entity, and used one synthesis page to explain how the family fit together.

That structure prevented two opposite mistakes.

The first is under-modeling: one giant “research agents” page that erases the responsibility of each role.

The second is over-modeling: creating a new named agent for every slightly different question until the tool picker looks like a restaurant menu written by a committee.

I am perfectly capable of over-organizing a folder (the folders are innocent; I am the problem), so the boundary matters:

A one-off task is not a role. A stable responsibility with repeatable evidence and output is.

Retrieval Order Matters

The curated-knowledge-first workflow does not mean “trust internal memory before reality.” It means “check whether useful precedent exists before rediscovering everything.”

The complete research flow still needs multiple layers:

1. Inspect the local codebase to learn how the project is actually organized.
2. Retrieve relevant internal patterns so prior decisions are not forgotten.
3. Consult external documentation when platform behavior, package compatibility, versions, or deprecations must be confirmed.

This sequence narrows the search space without promoting memory into authority.

If the curated corpus contains no clear guidance, the patterns researcher should say so. Its job is retrieval, not improvisation.

The same applies to the other roles. If the repository has no analogous implementation, the codebase researcher reports the gap. If official documentation conflicts or remains unclear, the documentation researcher reports that uncertainty instead of returning a convenient answer.

The stop condition is part of the role. Without one, every specialist eventually becomes a generalist with a themed name.

The Output Contract Is Half the Role

Agent roles are often described only by what they should think about. That is not enough.

The codebase researcher specification asks for project organization, state management, data-layer patterns, reference implementations, conventions, and constraints. The documentation researcher asks for compatibility, concepts, implementation guidance, recommended patterns, gotchas, and references. The patterns researcher asks for relevant patterns, principles, anti-patterns, and recommendations.

Those output shapes make the roles composable. A planning agent can consume three reports without guessing what each one was supposed to contain.

They also make evaluation possible. You can check whether the codebase report includes real paths. You can check whether the documentation report names its references and flags outdated material. You can check whether the pattern report says “nothing relevant found” when the corpus is empty.

“Research thoroughly” cannot be tested. “Return two analogous files with paths, or report that none were found” can.

That is the same shift from adjective to observable behavior that shaped the operating contract in Part 1.

When Not to Delegate

Three well-bounded roles do not imply that every task needs three agents.

A typo does not require a research stack. A localized change with an obvious existing pattern may need only the codebase evidence already in front of you. A package migration may need documentation research but no new internal taxonomy.

Delegation has a coordination cost. More reports mean more reconciliation, more duplicated context, and more opportunities to ask three agents the same vague question.

Use a specialist when its independent evidence changes the decision. If the answer will not affect the implementation, the delegation is ceremony.

The goal is not to maximize agent count. It is to keep different kinds of evidence from impersonating one another.

Lessons Learned

The first lesson was that role boundaries should follow epistemology before technology. Ask where the agent is allowed to know things from, not only which framework appears in its name.

The second lesson was that a reusable role needs a stable responsibility, an evidence boundary, an output contract, and a stop condition. Without those, it is just a long prompt with a badge.

The third lesson was that curated knowledge is a retrieval layer, not final authority. Local code explains the repository. Official sources explain the platform. Internal precedent explains prior intent.

And the final lesson was restraint. Do not create an agent because a task has a noun. Create one when a repeatable responsibility needs its own evidence and output.

Take the broadest research prompt in your workflow and underline every source it might consult. If those sources answer different kinds of questions, you may not need a smarter super-agent.

You may need clearer boundaries.

Previous: Part 1 — “A Prompt Is Not a Policy.”

Next: Part 3 — “‘Looks Good’ Is Not Verification: Give Coding Agents an Evidence Matrix.”