adversarial-investigation skill — multi-agent adversarial investigation workflow for hard or recurring bugs

SKILL.md

name	adversarial-investigation
argument-hint	describe the problem, symptoms, and what has been tried
description	Multi-agent adversarial investigation workflow for hard or recurring bugs. Use when the user asks for root-cause analysis, adversarial debugging, multi-agent investigation, a deep dive, or when symptoms contradict the obvious reading of the code. Best for intermittent, cross-stack, data-dependent, or previously failed fixes. Do not use for routine lint/type errors or small single-file bugs.

Adversarial Investigation

Use this skill when a normal read-edit-test pass is unlikely to be enough. The goal is consensus on scope, root cause, fix, and verification, backed by receipts.

Evidence Standard

Every claim needs a receipt:

• Code behavior: executable file:line, not comments.
• Runtime behavior: raw logs, traces, database/query output, browser console/network output, or saved artifacts.
• History/context: issue, PR, commit, changelog, or design document.

Code proves what can happen. Runtime evidence proves what did happen. If those conflict, investigate the conflict.

Roles

Run independent passes before converging:

• Lead: tracks symptoms, hypotheses, gaps, and evidence. Does not decide root cause early.
• Code Analyst: traces relevant code paths end to end, including callers, data flow, error handling, and tests.
• Runtime Analyst: inspects logs, traces, database state, browser/network output, and reproduction evidence when available.
• Explorer: checks git history, issues, PRs, docs, dependencies, and adjacent implementations.
• Devil's Advocate: attacks the leading hypothesis and demands disconfirming searches.

Use fewer roles only when the problem is narrower, but keep the adversarial standard: one pass builds the case and one pass tries to falsify it.

Workflow

1. Restate the user-visible symptoms verbatim.
2. Inventory what is known, unknown, and merely assumed.
3. Map all plausible code and runtime paths that could produce the symptoms.
4. Generate competing hypotheses.
5. For each hypothesis, predict what evidence should exist if true and if false.
6. Search for both confirming and disconfirming evidence.
7. Kill, park, or keep hypotheses with receipts.
8. Converge only when every symptom is covered and no live hypothesis explains the evidence better.
9. Propose the smallest fix that addresses the root cause.
10. Define verification: regression test, reproduction check, log/metric check, or manual workflow.

Output

Lead with findings:

• Root cause, with evidence chain.
• Fix recommendation.
• Verification plan.
• Rejected hypotheses and why.
• Residual risk or missing evidence.

If root cause is not proven, say what is still missing instead of guessing.