adversarial-validator

July 6, 2026 · View on GitHub

Operator documentation for the adversarial-validator agent in the han plugin. This document helps you decide when and how to dispatch the agent. For what the agent does internally, read the agent definition at han-core/agents/adversarial-validator.md.

See also: Plugin landing page · All agents · All skills

TL;DR

What it does. Assumes investigation evidence is wrong and the planned fix will fail. Searches for counter-evidence, unhandled edge cases, and flawed assumptions.
When to dispatch it. An investigation has produced a root cause and a fix plan, and you want the analysis adversarially validated before code lands. Always dispatched by /investigate and by /research (the adversarial-validation step at the end of every research pass). Required by /gap-analysis swarms at every size (which run by default) and by /iterative-plan-review team mode. Also dispatched by /code-overview, where it re-reads the code to verify a drafted overview's claims for accuracy rather than to validate a fix. /code-review also dispatches it, at Step 7.4, to re-read the change and confirm, demote, or drop each finding on the consolidated finding list.
What you get back. Numbered V# validation items, each with a strategy, hypothesis, investigation steps, result (Confirmed / Refuted / Partially Refuted), and an impact statement. Plus a confidence assessment and remaining risks.

Key concepts

Default posture: everything is wrong until proven right. The agent assumes the investigation reached the wrong conclusion and the fix will fail. The work is to try to disprove the analysis, not confirm it.
Four strategies, three always required. The agent must always attempt three strategies: challenge the evidence, challenge the fix, and challenge the assumptions. A fourth strategy, challenge the evidence-gathering integrity, applies whenever the inputs include gathered evidence, external sources, or research artifacts. That is always the case for an investigation evidence summary or a research run. It asks whether any item was planted, injected, astroturfed, stale, or single-sourced. Skipping an applicable strategy makes the validation incomplete.
Counter-evidence has the same rigor as evidence. A refutation requires the same file_path:line_number plus snippet plus reasoning that the original investigation required. "Looks wrong" is not a refutation.
Stale-evidence check is mandatory. The agent verifies that cited files and line numbers still match the codebase. Evidence from an old branch is not evidence.
Confidence assessment is not optional. Every run closes with a High / Medium / Low confidence level and a rationale grounded in what the validation found.

When to use it

Dispatch when:

An investigation has produced a root cause analysis and a planned fix, and you want it challenged before code is written. /investigate dispatches this agent automatically.
A research pass has reached a recommendation and you want its reasoning and sources attacked at the synthesis layer before the recommendation is trusted. /research always dispatches this agent as the adversarial-validation step at the end of every pass.
A gap analysis has produced gaps with claimed evidence and you want each gap challenged for confirmability. /gap-analysis dispatches this agent by default at every swarm size.
An iterative plan review is in team mode and you want the plan's assumptions attacked. /iterative-plan-review dispatches this agent in team mode.
A code overview has been drafted and you want its claims checked against the code before a reader trusts them. /code-overview dispatches this agent to validate the overview's accuracy, the stated why most of all, never to judge the code's quality.
A code review has produced a finding list and you want each finding re-attacked against the code before a human reads it. /code-review dispatches this agent at Step 7.4 to confirm, demote, or (with concrete counter-evidence) drop each finding, judging the finding's reasoning against the change rather than trusting the producing agent.
A team member has proposed a fix or change and you want a second adversarial opinion before merging.
A high-stakes incident response is winding down and you want to confirm the post-mortem's root cause and remediation hold up under challenge.

Do not dispatch for:

Discovering the root cause in the first place. Use evidence-based-investigator or /investigate.
Drafting a fix or plan. Use /plan-implementation or write the plan yourself; this agent validates plans, it does not write them.
Performing the code review itself. Use /code-review for correctness, style, and compliance. It dispatches this validator internally at Step 7.4 to re-check its finding list. But the validator judges whether a finding's reasoning holds against the code, not whether the code is clean.
Architectural assessment. Use /architectural-analysis. The validator does not synthesize architectural recommendations.
Self-evaluation of an agent's own output. The validator must run against another agent's output, not its own.

How to invoke it

Dispatch via the Agent tool with subagent_type: han-core:adversarial-validator. Give it:

The evidence summary. The full numbered evidence list from the investigation (E1, E2, …) or the gap list from a gap analysis (G-NNN).
The root cause analysis. A short statement of the root cause the investigation reached.
The planned fix. Per-file changes, function signatures, logic adjustments. Without a planned fix the agent cannot attack what is going to ship.
Project context, optional. Coding standards, ADRs, framework conventions the fix should respect.

Example prompts:

"Validate this investigation: [paste evidence summary, root cause, and planned fix]. Try to break the fix and find unhandled edge cases."
"Adversarially validate the gap analysis at gap-analysis-source.md. For each gap, search the current state for counter-evidence."
"The team is about to ship this auth-rotation plan. Challenge the assumptions before we commit."

What you get back

A minimum of 5 numbered V# validation items spread across the applicable strategies: Challenge the Evidence, Challenge the Fix, and Challenge the Assumptions. When the inputs include gathered or external evidence, items also cover Challenge the Evidence-Gathering Integrity. Each item names the strategy, the hypothesis under test, what was investigated (files read, commands run, greps performed), the result (Confirmed / Refuted / Partially Refuted), and the impact.
A Confidence Assessment (High / Medium / Low) with a rationale that points at the validation items behind the call.
A Remaining Risks section listing known unknowns, areas not fully validated, and assumptions the agent could not verify.

Every refutation includes counter-evidence at the same rigor as the original investigation. Every confirmation includes what was checked and why it supports the finding.

How to get the most out of it

Feed it the full evidence list, not a summary. The agent attacks evidence item by item. A summary collapses the attack surface.
Include the planned fix in detail. Without per-file changes and signatures the agent cannot run the fix-blast-radius checks (searching for callers, hunting for race conditions, verifying error paths).
Run it before, not after, implementation. The whole point is to catch flawed reasoning before code lands. Re-running it after a fix has shipped is a different exercise (post-mortem confirmation).
Take refutations seriously. A refuted evidence item is the most valuable output the agent produces. It means the original investigation was wrong at that point and the fix likely would have shipped a wrong answer.
Honor the confidence level. When confidence is Medium or Low, the agent has flagged that something is unresolved. Push back on the original investigation rather than overriding the validator.

Cost and latency

The agent runs on sonnet. A single validation pass typically runs in a few minutes (scope-dependent). The agent is designed to run once per investigation or gap analysis, not iteratively. If validation surfaces a refutation, fix the underlying investigation and re-run end-to-end rather than asking the validator to re-validate its own findings.

Plugin landing page. The front door.
Agents Index. All agents, grouped by role.
evidence-based-investigator. The sibling agent the validator usually attacks. Investigators gather, validators falsify.
/investigate. Always dispatches this agent after the fix plan is drafted.
/research. Always dispatches this agent as the adversarial-validation step at the end of every research pass, attacking the recommendation and its sources.
/gap-analysis. Required swarm role at every size. The swarm runs by default.
/iterative-plan-review. Dispatches this agent in team mode.
/code-overview. Dispatches this agent to validate a drafted overview's accuracy against the code before the reader sees it.
/code-review. Dispatches this agent at Step 7.4 to re-attack the consolidated finding list against the code, confirming, demoting, or dropping each finding before a human reads the review.
agent-domain-focus.md. Why the agent uses precise falsification vocabulary and named anti-patterns.
multi-agent-economics.md. Why this agent is the canonical second-opinion pattern across the plugin.

adversarial-validator

TL;DR

Key concepts

When to use it

How to invoke it

What you get back

How to get the most out of it

Cost and latency

Sources

Karl Popper: Falsificationism

Gary Klein: Pre-Mortem

Red Teaming