The Specialist Checkpoint Pattern: When to Split One Agent Into Five

For a year I ran a single generalist code-review agent. It wrote the review for every PR — Spring Boot refactors, Hibernate queries, Dockerfile tweaks, SQL migrations, security patches. The reviews were fine. They were not good.

The agent flagged "consider adding a comment" on database migrations with no rollback plan. It approved security changes that introduced timing attacks. It missed obvious N+1 queries. It caught code smells; it missed category errors.

The fix was obvious in retrospect: the single-prompt generalist was spread too thin to be anywhere near expert on every category. The pattern that replaced it is five smaller agents that fire only when their domain is relevant.

The one thing to take from this post: one prompt can't be an expert at everything. Four specialists that fire only when relevant beat a 2,000-line monolith system prompt.

The specialist pattern

Four review-time specialists:

SpecialistFires whenLooks for
ic-database-checkpointPR touches migrations, JPA entities, SQL, Hibernate configN+1 queries, missing indexes, non-reversible migrations, isolation level choices, connection pool impact
ic-security-checkpointPR touches auth, encryption, logging, input validation, dependenciesOWASP top 10, secret handling, PII, auth bypass, injection, dependency CVEs
ic-performance-checkpointPR touches query layer, loops with I/O, caching, concurrent codeJVM tuning, pool exhaustion, @Transactional strategy, latency SLA impact, memory pressure
ic-devops-checkpointPR touches Dockerfile, pipeline YAML, EBS config, deploymentBuild reproducibility, deployment safety, rollback readiness, ALB/CDN config, env drift

Each specialist has 300–500 lines of focused instructions and only looks at its domain. The generalist reviewer still runs — it coordinates the specialists and makes the final accept/reject call — but it delegates deep expertise.

When the specialist fires

Not every PR fires every specialist. The trigger logic is in .devin/workflows/_shared/ic-flow.csv:

1# Pseudocode: trigger-pattern format
2specialist, trigger_pattern, required
3ic-database, "src/main/**/dao/**|liquibase/**|*.sql", true
4ic-security, "SecurityConfig|JwtAuthFilter|@PreAuthorize|password|encrypt", true
5ic-performance, "pom.xml|@Transactional|HikariConfig|@Cacheable", if_touched
6ic-devops, "Dockerfile|azure-pipelines|docker-compose|*.yml", true

The reviewer agent reads this file at the start of a review, matches the PR diff against each pattern, and fires only the specialists whose trigger matches. A pure UI-copy change fires zero specialists; a DB migration fires three; a dependency bump fires security + maybe performance.

The measurement

I ran 80 PRs through both configurations and compared the review quality:

True positivesFalse negativesReview tokens
Monolith reviewer61% of real issues39% missedbaseline
Reviewer + specialists84% of real issues16% missed+42%

The specialist pattern catches 37% more real issues at 42% more tokens. For a code-review agent, where false negatives land in production, the trade is a bargain.

The categorical breakdown explains why:

  • Database issues: monolith caught 48%, specialists caught 91%. The specialist knows what a non-reversible migration looks like; the generalist doesn't.
  • Security issues: monolith caught 55%, specialists caught 88%. The generalist nitpicked variable names on security PRs; the specialist flagged a timing-attack-prone comparison.
  • Performance issues: monolith caught 44%, specialists caught 78%. The specialist spots the N+1 the generalist read right past.
  • Everything else: roughly tied. The generalist is still useful on code smell and style.

What makes a good specialist prompt

Three traits I observed in the specialists that worked:

1. Focused checklist, not open ended. The database specialist has 23 explicit checks ("does the migration have an explicit rollback?" "does any new query join across tenants?"). The generalist had "review for issues." Narrow prompts stay sharp.

2. Required evidence. Each finding the specialist raises must cite a file:line. "There's a potential N+1 somewhere" is not an acceptable finding; "N+1 in FundServiceImpl.java:224 — findByFundId is inside a loop" is.

3. Explicit non-domain exclusions. The security specialist's prompt literally says "do not comment on code style, formatting, or anything not security-relevant." Without that exclusion, specialists drift into generalism and the token cost explodes.

What the gating looks like

Specialist checkpoint gating: a PR is matched against triggers; the specialists whose triggers fire (database, security, performance) run in parallel and the reviewer merges their findings into one verdict

A review session with three specialists running in parallel takes ~2 minutes and $0.80. A review that found a critical bug saves hours of human time plus one production incident. The economics are good enough that I run the specialists on every qualifying PR, not just the big ones.

When specialists are the wrong pattern

For planning or ideation. Specialists are review-time animals — they verify a done thing. During planning, you want the generalist to think broadly, not a security checker on standby nitpicking a diagram.

For small codebases. If your repo is 500 files, you don't need four specialists; the generalist is fine. The pattern pays off at scale, where no single prompt can hold expert-level knowledge of every subsystem.

When your rubrics overlap too much. If your "security" and "devops" specialists are flagging the same findings, you have one specialist in two files. Consolidate.

The maintenance tax

The downside: each specialist is a prompt I now have to keep sharp. When Spring Boot 4 drops and @Transactional semantics change, the performance specialist's prompt needs an update. Four specialists = four maintenance surfaces. I accept the tax because the review quality is worth it, but it's real.

Attribution: The patterns and specific numbers in this post come from Devin with the ic-documentation agent framework my team maintains — not from an independent reproduction. See the series intro for the full disclosure. The patterns themselves generalize to any coding-agent setup.

Up next: Read-only subagents are 5× cheaper — the exploration/research pattern (coming soon).