[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M70FQP9J694HBBXFNR7TCBER":3,"skill-same:01M70FQP9J694HBBXFNR7TCBER":102},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":22,"publishedAt":43,"linkOnly":44,"markdownContent":45,"markdownBody":46,"frontMatter":47,"refName":48,"commitSha":49,"skillDirectory":50,"forksCount":13,"repositoryHtmlUrl":51,"repositoryHomepageUrl":6,"ownerHtmlUrl":52,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":53,"install":54,"resources":67},"01M70FQP9J694HBBXFNR7TCBER","adversarial-investigate",null,"Automated adversarial investigation framework using Claude Code Agent Teams. Spawns 3 persistent teammates (Investigator A, Investigator B, Synthesizer C) to diagnose the root cause of a known bug through 4 rounds of isolated analysis, synthesis, critique, and reconciliation. A traces FORWARD from the bug trigger; B traces BACKWARD from the failure point; both investigate the same evidence independently with zero knowledge of each other. C reviews both and synthesizes; A and B critique C from their original contexts; C reconciles into a final diagnosis. Allows \"insufficient evidence\" as a valid exit — does not force premature commitment to a cause. Trigger as the diagnosis stage of a fix-pipeline, after fix-reproducer (or directly off problem-statement.md if reproduce was skipped).","SirTheOracle\u002Fforge-toolkit","SirTheOracle","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F264051384?v=4","01M70FNRYMQR4XHVN77S3NJPAW","01M70FNRZAGW58XJ1CC6JRY1PA",0,"MIT","https:\u002F\u002Fgithub.com\u002FSirTheOracle\u002Fforge-toolkit\u002Fblob\u002Fmain\u002Fskills\u002Fadversarial-investigate\u002FSKILL.md",[17],{"categoryNo":18,"categoryName":19,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42],"adversarial","adversarial investigate","investigate","as","framework","bug","investigator","diagnosis","critique","valid","code","analysis","knowledge","fix","pipeline","reproducer","agent teams","problem","reviews","reconciliation","2026-11-10 10:12:30",false,"---\nname: adversarial-investigate\ndescription: >\n  Automated adversarial investigation framework using Claude Code Agent Teams.\n  Spawns 3 persistent teammates (Investigator A, Investigator B, Synthesizer C)\n  to diagnose the root cause of a known bug through 4 rounds of isolated\n  analysis, synthesis, critique, and reconciliation. A traces FORWARD from the\n  bug trigger; B traces BACKWARD from the failure point; both investigate the\n  same evidence independently with zero knowledge of each other. C reviews both\n  and synthesizes; A and B critique C from their original contexts; C\n  reconciles into a final diagnosis. Allows \"insufficient evidence\" as a valid\n  exit — does not force premature commitment to a cause. Trigger as the\n  diagnosis stage of a fix-pipeline, after fix-reproducer (or directly off\n  problem-statement.md if reproduce was skipped).\n---\n\n# Adversarial Investigation Framework\n\n## Overview\n\nThree persistent teammates investigate the root cause of a known bug through 4 rounds. The critical design principle is **information isolation** — A and B each have their own context window and never see each other's work. Only Synthesizer C sees both. A and B critique C from their original contexts (in Round 3 they see only their own isolated review file, never C's full synthesis or the other investigator's hypotheses). C reconciles into a final diagnosis.\n\nThis skill differs from `adversarial-proposal` in three important ways:\n\n1. **Inputs are richer** — beyond a problem statement, investigators read repro.md (if present), the original build pipeline's artifacts (read-only context), and operate in an env-aware mode (prod is observational; dev is interactive).\n2. **Output is a diagnosis, not a plan** — `diagnosis.md` commits to a root cause with evidence chain, or honestly admits insufficient evidence and specifies what data would resolve the ambiguity.\n3. **A third valid exit exists** — INSUFFICIENT EVIDENCE is not a failure; it's a structurally legitimate output that signals the fix-pipeline to gather more data before proceeding.\n\nThe full tool-call sequence lives in `references\u002Fagent-teams-workflow.md`. **Read that file before orchestrating.** This document is the high-level guide.\n\n## When to Use\n\n- As the diagnosis stage of a fix-pipeline, after a bug has been reported (and ideally reproduced)\n- When the cause of a known failure is non-obvious or could plausibly be in multiple places\n- When prior fixes for similar-looking bugs failed to resolve the underlying cause\n- When the bug surfaces inconsistently and you suspect compound conditions\n\n## When NOT to Use\n\n- **Trivial bugs** — typos, one-line errors with obvious cause. Just fix them.\n- **Bugs where the cause is already known** — don't re-deliberate. Go straight to fix-plan.\n- **Build-pipeline planning** — use `adversarial-proposal` for forward-looking work; investigation is for diagnosing known failures.\n- **Bugs where reproduction itself is the problem** — get fix-reproducer to land first, then investigate.\n\n## Prerequisites\n\nRequires Claude Code Agent Teams:\n\n```bash\n# In ~\u002F.claude\u002Fsettings.json\n{ \"env\": { \"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS\": \"1\" } }\n```\n\nTakes effect on new Claude Code sessions. If Teams is not available, fall back to `references\u002Fsubagent-fallback.md` — functionally equivalent but loses cross-round teammate persistence.\n\n## Modes\n\n| Mode | Flag | Behavior |\n|------|------|----------|\n| **Default** | — | Fully automated. Lead orchestrates all rounds without pausing. |\n| **Interactive** | `--interactive` | Pauses after Round 1 (user reviews investigations) and after Round 2 (user reviews synthesis) before continuing. |\n\n**Expected runtime**: ~20–30 min for a full run (longer than `adversarial-proposal` because investigators read more context — problem statement, repro.md, original-pipeline artifacts, plus source). Convergence-path runs are shorter (~10–15 min). INSUFFICIENT EVIDENCE outcomes typically resolve within Round 2 once C confirms no investigator hit ground truth.\n\n## Inputs\n\nRequired:\n\n- `--output-dir` — path to the fix directory. `problem-statement.md` lives here; `diagnosis.md` and supporting artifacts will be written here.\n- `--env prod | dev` — which environment the bug exists in. Affects investigation tooling (prod = observational; dev = interactive).\n\nOptional:\n\n- `--original-slug` — slug of the original build pipeline whose feature has the bug. Enables read-only context access to that pipeline's `final-plan.md`, `implementation.md`, and `coder-report.md`.\n- `--interactive` — pause at Round 1 and Round 2 checkpoints for user review.\n\n## Architecture\n\n```\nROUND 0  Setup: read inputs → determine env path → strategy pair → team → tasks\nROUND 1  investigator-a + investigator-b investigate in parallel (isolated)\n           A: traces FORWARD from the bug trigger\n           B: traces BACKWARD from the failure point\n           ─► investigation-A.md, investigation-B.md\n         ▼  quality gate + convergence check + (interactive) checkpoint 1\nROUND 2  synthesizer-c reads both → produces 3 artifacts\n           ─► investigation-C.md, review-for-A.md, review-for-B.md\n         ▼  artifact gate + (interactive) checkpoint 2\nROUND 3  A and B resume from their Round 1 context, each reads ONLY its own\n         review file → SendMessage feedback back to lead\nROUND 4  synthesizer-c resumes → reconciles both critiques\n           ─► reconciliation-notes.md + diagnosis.md\nROUND 5  shutdown all teammates, TeamDelete, present to user\n```\n\n### Strategy pair\n\n| Investigator | Strategy | Approach |\n|---|---|---|\n| **A** | Forward-from-trigger | Start at the action that triggers the bug (per repro.md or problem-statement.md) and walk forward through the code\u002Fdata flow, noting assumptions made and verifying state at each transition until the failure manifests. Catches: \"an early assumption turned out to be false later.\" |\n| **B** | Backward-from-failure-point | Start at the visible failure (error, wrong output, exception) and walk backward through call stacks, data dependencies, and state transitions to find what produced it. Catches: \"this state was wrong by the time we got here, where did it come from.\" |\n\nBoth end up needing to understand the same code, but they enter it from different ends, and they tend to notice different things.\n\n### Why isolation works\n\nEach teammate has its own context window. A and B share no conversation history. All communication goes through the lead. The lead NEVER forwards A's work to B or vice versa. Round 3 isolation is maintained via per-investigator review files (`review-for-A.md`, `review-for-B.md`) that each teammate reads exclusively.\n\n### Why teammates stay alive\n\n- A and B retain full Round 1 investigation context when critiquing C in Round 3. This makes their pushback grounded in *why* they chose their original hypothesis ranking, not just what the review file claims.\n- C retains its synthesis reasoning from Round 2 when reconciling in Round 4.\n\nPersistence is the main reason to use Teams over the fallback.\n\n---\n\n## How to Execute\n\nYou (the lead) orchestrate everything. The exact tool-call sequence is in `references\u002Fagent-teams-workflow.md`. Below is the orchestration checklist.\n\n### Step 0 — Gather context and detect inputs\n\n**0A. Empty-args short-circuit.** If invoked without `--output-dir`, without `--env`, or without a problem statement on disk, stop immediately. Respond:\n\n> \"This skill requires a problem statement at {output-dir}\u002Fproblem-statement.md and the --env flag. Provide --output-dir and --env (one of `prod` | `dev`), and ensure problem-statement.md exists.\"\n\nDo NOT attempt to investigate without these inputs.\n\n**0B. Read inputs from `{output_dir}`:**\n\n- `problem-statement.md` — required\n- `repro.md` — if present, included in investigators' input. If absent, investigators must work from the problem statement alone.\n\n**0C. Read original pipeline artifacts (if `--original-slug` provided):**\n\nRead-only context from `.dev\u002Fproposals\u002F{original-slug}\u002F`:\n- `final-plan.md` — what the feature was supposed to do\n- `implementation.md` — what was actually built (exact diffs)\n- `coder-report.md` — what was committed and what tests ran\n\nThese are **context, not suspects.** The investigators read them to understand what was built, not as a list of likely causes.\n\n**0D. Confirm `--env`:**\n\n`prod` or `dev`. The env affects investigator tooling guidance:\n- **dev**: investigators may run code locally, add temporary logging, query dev DB, step through. Active investigation.\n- **prod**: investigators are observational — read logs, query telemetry, read code. They may NOT run code in production. Passive investigation.\n\n**Hybrid case (prod bug reproducible in dev).** If `--env prod` was passed but `repro.md` classifies the bug as REPRODUCED or PARTIALLY REPRODUCED in dev, dev-mode investigation IS permitted to test hypotheses about the prod bug. Investigators must explicitly record any dev-bridging in their evidence chain (e.g., \"verified hypothesis H2 by reproducing in dev — dev\u002Fprod parity confirmed for {component}\"). The diagnosis must still answer for prod.\n\nThe skill is agnostic about specific tools. The runtime composes Railway-aware skills, Playwright, log scrapers, etc., based on what's available.\n\n**0E. Exploration budget.** Before spawning A and B, the lead reads **at most 3–5 files** to orient. The investigators re-read source independently — that's the point. Over-exploration in the lead burns context that A\u002FB will duplicate anyway.\n\n**0F. Evidence floor (early bail-out).** Before spawning teammates, confirm at least one of these is present:\n\n- `repro.md` exists and classifies as REPRODUCED or PARTIALLY REPRODUCED\n- `--original-slug` is provided (gives access to feature artifacts as context)\n- The problem statement contains concrete telemetry references (logs, error tracking IDs, stack traces, response bodies)\n\nIf none are present (only a vague problem statement), surface to the user before spawning teammates:\n\n> \"No reproduction, no original-pipeline context, and no telemetry references in the problem statement. Investigation will likely return INSUFFICIENT EVIDENCE. Recommend running fix-reproducer first or gathering data before proceeding. Continue anyway?\"\n\nWait for explicit user confirmation. This avoids burning Teams budget on a structurally guaranteed INSUFFICIENT EVIDENCE outcome.\n\n### Step 1 — Team setup\n\n```\nTeamCreate(team_name=\"inv-\u003Cshort-slug>\", description=\u003Cshort>)\n# Create 5 tasks (A, B, C, critique, reconcile) with dependency chain\n```\n\nDetails in `references\u002Fagent-teams-workflow.md` §\"Round 0\".\n\n### Step 2 — Round 1: Spawn A and B in parallel (same turn)\n\nTwo `Agent(team_name=..., name=\"investigator-a\", ...)` calls in a single message. Each prompt embeds the **investigator role** (`agents\u002Finvestigator.md`), the **investigation format** (`references\u002Finvestigation-format.md`), the assigned strategy, the **isolation rule** (see below), the **env mode** (prod or dev), and explicit **\"wait, don't exit\"** instructions.\n\n**Investigator A prompt must include:**\n- Full content of `problem-statement.md`\n- Full content of `repro.md` (if present)\n- Original pipeline artifacts (if `--original-slug`) marked clearly as CONTEXT, NOT SUSPECTS\n- Investigator role (from `agents\u002Finvestigator.md`)\n- Strategy assignment: **Forward-from-trigger**\n- Env mode and what investigation is permitted\n- Output path: `{output_dir}\u002Finvestigation-A.md`\n- Isolation rule: do NOT read investigation-B.md or any other investigation files\n- Anti-anchoring requirement: must list ≥2 alternative hypotheses even if a leading candidate exists\n- Symptom-confirmation challenge: must explicitly answer \"could the visible error be a symptom of a deeper cause?\"\n\n**Investigator B prompt must include:**\n- Same problem statement, repro, and original-pipeline context\n- Same role file\n- Strategy assignment: **Backward-from-failure-point**\n- Same env mode, output path differing (`investigation-B.md`), same isolation rule, same anti-bias requirements\n\nThen the lead idles — teammate \"done\" messages arrive as new conversation turns. No polling.\n\n### Step 3 — Gates after Round 1\n\n**Artifact gate (required, run first)**: verify on disk that `investigation-A.md` and `investigation-B.md` both exist and are non-empty. If either is missing or empty, `SendMessage(to=\"investigator-a|b\", message=\"Your investigation file at {path} is missing or empty. Write your full investigation to that path before signaling done.\")`. Do not proceed to the quality gate until both files exist on disk.\n\n**Quality gate**: each investigation has required sections — at least 2 hypotheses (top + alternatives), evidence per hypothesis, explicit symptom-confirmation answer, ≥3 concrete code\u002Flog references. Failure → `SendMessage(to=\"investigator-a|b\", message=\"revise: \u003Cspecific>\")`. Teammate resumes with full context.\n\n**Convergence check**: did A and B independently land on the same top hypothesis with the same evidence? If yes, skip to §\"Convergence path\" in `agent-teams-workflow.md` — spawn C for lightweight review only, no Round 2\u002F3.\n\n**(Interactive) checkpoint 1**: pause for user review of investigation-A\u002FB.\n\n### Step 4 — Round 2: Synthesizer C\n\nSpawn `synthesizer-c` teammate. Prompt embeds `agents\u002Finv-synthesizer.md` and instructs Phase 0 (independent code\u002Fevidence exam) before reading investigations. Produce THREE files.\n\nSynthesizer C is required to:\n\n- Phase 0: read source files and evidence directly, before reading A or B's work\n- Phase 1: read investigation-A and investigation-B\n- Phase 2: cross-verify the highest-evidence hypotheses against the actual code\n- Phase 3: synthesize into investigation-C.md with C's own committed top hypothesis, ranked alternatives, and a tentative convergence-status assessment\n- Phase 4: write isolated review files for A and B (no mention of the other investigator)\n\n### Step 5 — Round 2 artifact gate (required)\n\nBefore Round 3, **verify on disk**:\n- `investigation-C.md` exists\n- `review-for-A.md` exists\n- `review-for-B.md` exists\n\nIf any is missing, `SendMessage(to=\"synthesizer-c\", message=\"\u003Cname the missing file>\")`. Do not proceed with partial artifacts.\n\n**(Interactive) checkpoint 2**: pause for user review of investigation-C.md.\n\n### Step 6 — Round 3: Critique (pinned teammate descriptions)\n\nTwo `SendMessage` calls in one turn, using these exact `description` values:\n- `\"Critic A: Round 3 feedback on investigation-A\"`\n- `\"Critic B: Round 3 feedback on investigation-B\"`\n\nEach message embeds `agents\u002Finv-critic.md` and the per-investigator isolation rule (read ONLY own review file + own investigation). Teammates resume with full Round 1 context.\n\nThe critic role specifically asks each investigator: \"Does C's synthesis fairly represent your evidence? Did C address the alternative hypotheses you ranked highly? If not, do you accept C's ranking, or do you have evidence that contradicts it? Does C's committed top hypothesis explain ALL the evidence, or only the symptom?\"\n\n### Step 7 — Round 4: Reconciliation\n\nWhen both critiques arrive, `SendMessage(to=\"synthesizer-c\", ...)` with both feedback bodies inline and `agents\u002Finv-reconciler.md` embedded.\n\nC produces TWO files:\n\n- `diagnosis.md` — the deliverable\n- `reconciliation-notes.md` — one line per critique: `A: \u003Cpoint> → ACCEPTED\u002FPARTIAL\u002FREJECTED — \u003Creason>` (reduces reconciler-bias blind spot)\n\nC is required to commit to a `convergence_status` in diagnosis.md:\n\n- **CONVERGED** — single root cause identified with high confidence, evidence chain explains all observed symptoms\n- **PARTIALLY CONVERGED** — top hypothesis is supported but meaningful uncertainty remains. diagnosis.md commits to the top hypothesis, flags alternatives, and includes a `required_data` section listing what would resolve the uncertainty.\n- **INSUFFICIENT EVIDENCE** — cannot honestly commit to a cause given current evidence. diagnosis.md documents candidate hypotheses and includes a `required_data` section. The fix-pipeline orchestrator should escalate to the user or trigger data gathering before proceeding to fix-plan.\n\nINSUFFICIENT EVIDENCE is a legitimate output, not a failure. The reconciler is explicitly instructed not to manufacture false convergence under pressure.\n\n### Step 8 — Cleanup\n\n```\nSendMessage(to=\"investigator-a\", message={\"type\": \"shutdown_request\", ...})  # all three in parallel\n# Wait for shutdown acknowledgments (idle notifications)\nTeamDelete()\n```\n\nPresent `diagnosis.md` (+ `reconciliation-notes.md`) to the user.\n\n---\n\n## Isolation Rule (embed verbatim in investigator prompts)\n\n```\nISOLATION RULE — strict.\n\nAllowed reads:\n- Files listed under \"Source files\" in this prompt\n- problem-statement.md and repro.md in the current output directory\n- Files listed under \"Original pipeline context\" (if provided) — READ-ONLY, treat as context not suspects\n\nForbidden reads, in the current output directory:\n- investigation-A.md, investigation-B.md, investigation-C.md  (except your own investigation in Round 3)\n- review-for-A.md, review-for-B.md                            (except your own review in Round 3)\n- diagnosis.md, reconciliation-notes.md\n\nForbidden writes:\n- Any file under .dev\u002Fproposals\u002F{original-slug}\u002F  (read-only context)\n\nWhen you finish, SendMessage the team lead \"team-lead\" with a one-line\nplain-text summary including your committed top hypothesis. Then go idle —\ndo NOT exit. You will be messaged again in Round 3 to critique a synthesis\nof your work.\n```\n\nRound 3 adds: \"Read ONLY review-for-A.md (or review-for-B.md for B) and your own investigation-A.md. Do NOT read investigation-C.md, the other investigator's review, or the other investigator's investigation.\"\n\n---\n\n## diagnosis.md Structure\n\n```markdown\n# Diagnosis — {slug}\n\n## Convergence Status\n{CONVERGED | PARTIALLY CONVERGED | INSUFFICIENT EVIDENCE}\n\n## Environment\n{prod | dev}\n\n## Root Cause\n{For CONVERGED: the committed cause, stated precisely.\n For PARTIALLY CONVERGED: the top hypothesis, with caveats.\n For INSUFFICIENT EVIDENCE: \"No single cause can be committed to with current evidence. See Candidate Causes.\"}\n\n## Evidence Chain\n{For each step in the causal chain: what was observed, where (file:line, log reference, etc.),\n and how it connects to the next step. The chain should explain ALL observed symptoms,\n not just the most prominent one.}\n\n## Hypotheses Considered\n{Audit trail. Each hypothesis: name, evidence for, evidence against, verdict (committed\u002Frejected\u002Fdeferred), reason.}\n\n## Candidate Causes\n{Only present for PARTIALLY CONVERGED and INSUFFICIENT EVIDENCE.\n Each candidate: id, description, evidence supporting, evidence against,\n what makes it more or less likely than the others.}\n\n## Required Data\n{Only present for PARTIALLY CONVERGED and INSUFFICIENT EVIDENCE.\n Structured list of additional data that would distinguish remaining hypotheses:}\n\n```yaml\nrequired_data:\n  - id: D1\n    distinguishes: [hypothesis-2, hypothesis-3]\n    description: \"Production logs from auth service for the 5-minute window around the reported failure timestamp\"\n    source: \"Railway logs \u002F production\"\n    blocking_severity: high\n  - id: D2\n    distinguishes: [hypothesis-1, hypothesis-2]\n    description: \"Whether refresh-token expiry was extended in last deployment\"\n    source: \"Git history \u002F config diff\"\n    blocking_severity: medium\n```\n\n`blocking_severity` is one of `high | medium | low`:\n- `high` — fix-pipeline must not advance to fix-plan without this data\n- `medium` — fix-plan can proceed but should be revisited if this data later contradicts the chosen plan\n- `low` — nice-to-have for completeness; does not gate downstream stages\n\n## Symptom vs Cause Analysis\n{Explicit answer to: was the visible error a symptom of a deeper cause? If yes, what's upstream of where it manifests? If no, why is the visible error itself the cause?}\n\n## Confidence + Blocking Items\nCONFIDENCE: HIGH | MEDIUM | LOW\nBLOCKING_ITEMS: N\n```\n\n---\n\n## Bias Mitigations\n\n**Anchoring bias (investigator latches onto first plausible hypothesis).**\nInvestigator role file requires ≥2 alternative hypotheses, even when a leading candidate exists. Synthesizer role requires evaluating all hypotheses, not just top one.\n\n**Symptom-confirmation bias (investigator chases the visible error).**\nInvestigator role file requires explicit answer to: \"could the visible error be a symptom of a deeper cause? What's upstream of where it manifests?\"\n\n**Recency bias from original pipeline artifacts.**\nOriginal pipeline artifacts are framed as CONTEXT, NOT SUSPECTS in investigator prompts. The investigator role file is explicit: read them to understand what was built, not as a list of likely causes.\n\n**Reconciler bias toward own synthesis.**\nSame mechanism as adversarial-proposal:\n- `agents\u002Finv-reconciler.md` includes steelman \u002F perspective-test guidance\n- `reconciliation-notes.md` (required) forces explicit accept\u002Fpartial\u002Freject for every critique point\n- `--interactive` mode lets user review investigation-C.md before Round 3 critiques\n\n**Forced-convergence bias (reconciler manufactures a cause to look decisive).**\nReconciler role explicitly authorizes INSUFFICIENT EVIDENCE as a legitimate output. The reconciler is instructed not to commit to a cause if the evidence doesn't support it.\n\n---\n\n## Known Tradeoffs\n\n**Lead context pressure.** Orchestration across many rounds can fill the lead's window. Stay disciplined: the lead doesn't re-read source files (the teammates do). The lead reads problem-statement.md, repro.md, the three synthesis artifacts, and the final diagnosis. Everything else is teammate-scoped.\n\n**Strategy pair can mismatch.** If the bug doesn't fit a clear forward-trace\u002Fbackward-trace shape (for example, a timing-dependent issue with no clear \"trigger\" or \"failure point\"), the strategy pair may converge prematurely or both miss the cause. The investigator role includes an escape hatch: \"if the assigned strategy doesn't fit, note why and investigate naturally — but explain your reasoning.\"\n\n**Prod investigation is harder.** Without the ability to run code or add logging, prod investigators rely entirely on existing telemetry. If telemetry is sparse, INSUFFICIENT EVIDENCE will be the honest outcome. The skill does not penalize this — it surfaces it.\n\n---\n\n## Invoking the Skill\n\n### Direct prompt\n\n```\n\u002Fadversarial-investigate \\\n  --output-dir .dev\u002Ffixes\u002Fjwt-refresh-tokens\u002Fauth-token-refresh-race\u002F \\\n  --env prod \\\n  --original-slug jwt-refresh-tokens\n```\n\nFor an interactive run:\n\n```\n\u002Fadversarial-investigate \\\n  --output-dir .dev\u002Ffixes\u002F...\u002F... \\\n  --env dev \\\n  --original-slug ... \\\n  --interactive\n```\n\n### As a Claude Code command\n\n`~\u002F.claude\u002Fcommands\u002Fadversarial-investigate.md`:\n\n```\nRead .claude\u002Fskills\u002Fadversarial-investigate\u002FSKILL.md and\n.claude\u002Fskills\u002Fadversarial-investigate\u002Freferences\u002Fagent-teams-workflow.md,\nthen orchestrate the workflow.\n\nArguments: $ARGUMENTS\n```\n\nIf `$ARGUMENTS` is empty or missing required flags, follow Step 0A (empty-args short-circuit).\n\n---\n\n## Output Directory\n\n```\n{output_dir}\u002F\n├── problem-statement.md         ← Input (from orchestrator)\n├── repro.md                     ← Input (from fix-reproducer, if it ran)\n├── investigation-A.md           ← Round 1: Forward-from-trigger\n├── investigation-B.md           ← Round 1: Backward-from-failure-point\n├── investigation-C.md           ← Round 2: Synthesis (lead-only; absent on convergence)\n├── review-for-A.md              ← Round 2: A's eyes only (absent on convergence)\n├── review-for-B.md              ← Round 2: B's eyes only (absent on convergence)\n├── reconciliation-notes.md      ← Round 4: ACCEPT\u002FPARTIAL\u002FREJECT audit trail (absent on convergence)\n└── diagnosis.md                 ← Round 4: FINAL DELIVERABLE\n```\n\nThe presence or absence of `investigation-C.md` + reviews is the structural signal of which path ran:\n- **Full run**: all files present\n- **Convergence run**: investigation-A\u002FB + diagnosis.md only\n\n---\n\n## Reference Files\n\n| File | When to read | Purpose |\n|---|---|---|\n| `references\u002Fagent-teams-workflow.md` | Before orchestrating | Exact tool-call sequence for all rounds |\n| `references\u002Finvestigation-format.md` | When building investigator\u002Fsynthesizer prompts | Investigation template to embed |\n| `references\u002Fdiagnosis-format.md` | When building reconciler prompts | Final diagnosis template (matches diagnosis.md structure above) |\n| `references\u002Fsubagent-fallback.md` | Only if Teams is unavailable | Task-based fallback with file coordination |\n| `agents\u002Finvestigator.md` | Building A\u002FB prompts | Investigation role + strategy pair + bias mitigations |\n| `agents\u002Finv-synthesizer.md` | Building C's Round 2 prompt | Synthesis role with 3-file output spec + tentative convergence assessment |\n| `agents\u002Finv-critic.md` | Building Round 3 messages | Critique guidance (defend, accept, or counter the synthesis) |\n| `agents\u002Finv-reconciler.md` | Building Round 4 message | Bias-aware reconciliation + diagnosis.md spec + convergence status authorization |\n\n## Agent Roles Summary\n\n| Agent | File | Used in | Purpose |\n|---|---|---|---|\n| Investigator | `agents\u002Finvestigator.md` | Round 1 (A, B) | Independent investigation with assigned strategy + anti-bias requirements |\n| Synthesizer | `agents\u002Finv-synthesizer.md` | Round 2 (C) | Independent exam, synthesis, isolated review files, tentative convergence status |\n| Critic | `agents\u002Finv-critic.md` | Round 3 (A, B) | Review own isolated critique, defend or concede on grounds of evidence |\n| Reconciler | `agents\u002Finv-reconciler.md` | Round 4 (C) | Bias-aware reconciliation + final diagnosis + convergence status (including INSUFFICIENT EVIDENCE) |\n","# Adversarial Investigation Framework\n\n## Overview\n\nThree persistent teammates investigate the root cause of a known bug through 4 rounds. The critical design principle is **information isolation** — A and B each have their own context window and never see each other's work. Only Synthesizer C sees both. A and B critique C from their original contexts (in Round 3 they see only their own isolated review file, never C's full synthesis or the other investigator's hypotheses). C reconciles into a final diagnosis.\n\nThis skill differs from `adversarial-proposal` in three important ways:\n\n1. **Inputs are richer** — beyond a problem statement, investigators read repro.md (if present), the original build pipeline's artifacts (read-only context), and operate in an env-aware mode (prod is observational; dev is interactive).\n2. **Output is a diagnosis, not a plan** — `diagnosis.md` commits to a root cause with evidence chain, or honestly admits insufficient evidence and specifies what data would resolve the ambiguity.\n3. **A third valid exit exists** — INSUFFICIENT EVIDENCE is not a failure; it's a structurally legitimate output that signals the fix-pipeline to gather more data before proceeding.\n\nThe full tool-call sequence lives in `references\u002Fagent-teams-workflow.md`. **Read that file before orchestrating.** This document is the high-level guide.\n\n## When to Use\n\n- As the diagnosis stage of a fix-pipeline, after a bug has been reported (and ideally reproduced)\n- When the cause of a known failure is non-obvious or could plausibly be in multiple places\n- When prior fixes for similar-looking bugs failed to resolve the underlying cause\n- When the bug surfaces inconsistently and you suspect compound conditions\n\n## When NOT to Use\n\n- **Trivial bugs** — typos, one-line errors with obvious cause. Just fix them.\n- **Bugs where the cause is already known** — don't re-deliberate. Go straight to fix-plan.\n- **Build-pipeline planning** — use `adversarial-proposal` for forward-looking work; investigation is for diagnosing known failures.\n- **Bugs where reproduction itself is the problem** — get fix-reproducer to land first, then investigate.\n\n## Prerequisites\n\nRequires Claude Code Agent Teams:\n\n```bash\n# In ~\u002F.claude\u002Fsettings.json\n{ \"env\": { \"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS\": \"1\" } }\n```\n\nTakes effect on new Claude Code sessions. If Teams is not available, fall back to `references\u002Fsubagent-fallback.md` — functionally equivalent but loses cross-round teammate persistence.\n\n## Modes\n\n| Mode | Flag | Behavior |\n|------|------|----------|\n| **Default** | — | Fully automated. Lead orchestrates all rounds without pausing. |\n| **Interactive** | `--interactive` | Pauses after Round 1 (user reviews investigations) and after Round 2 (user reviews synthesis) before continuing. |\n\n**Expected runtime**: ~20–30 min for a full run (longer than `adversarial-proposal` because investigators read more context — problem statement, repro.md, original-pipeline artifacts, plus source). Convergence-path runs are shorter (~10–15 min). INSUFFICIENT EVIDENCE outcomes typically resolve within Round 2 once C confirms no investigator hit ground truth.\n\n## Inputs\n\nRequired:\n\n- `--output-dir` — path to the fix directory. `problem-statement.md` lives here; `diagnosis.md` and supporting artifacts will be written here.\n- `--env prod | dev` — which environment the bug exists in. Affects investigation tooling (prod = observational; dev = interactive).\n\nOptional:\n\n- `--original-slug` — slug of the original build pipeline whose feature has the bug. Enables read-only context access to that pipeline's `final-plan.md`, `implementation.md`, and `coder-report.md`.\n- `--interactive` — pause at Round 1 and Round 2 checkpoints for user review.\n\n## Architecture\n\n```\nROUND 0  Setup: read inputs → determine env path → strategy pair → team → tasks\nROUND 1  investigator-a + investigator-b investigate in parallel (isolated)\n           A: traces FORWARD from the bug trigger\n           B: traces BACKWARD from the failure point\n           ─► investigation-A.md, investigation-B.md\n         ▼  quality gate + convergence check + (interactive) checkpoint 1\nROUND 2  synthesizer-c reads both → produces 3 artifacts\n           ─► investigation-C.md, review-for-A.md, review-for-B.md\n         ▼  artifact gate + (interactive) checkpoint 2\nROUND 3  A and B resume from their Round 1 context, each reads ONLY its own\n         review file → SendMessage feedback back to lead\nROUND 4  synthesizer-c resumes → reconciles both critiques\n           ─► reconciliation-notes.md + diagnosis.md\nROUND 5  shutdown all teammates, TeamDelete, present to user\n```\n\n### Strategy pair\n\n| Investigator | Strategy | Approach |\n|---|---|---|\n| **A** | Forward-from-trigger | Start at the action that triggers the bug (per repro.md or problem-statement.md) and walk forward through the code\u002Fdata flow, noting assumptions made and verifying state at each transition until the failure manifests. Catches: \"an early assumption turned out to be false later.\" |\n| **B** | Backward-from-failure-point | Start at the visible failure (error, wrong output, exception) and walk backward through call stacks, data dependencies, and state transitions to find what produced it. Catches: \"this state was wrong by the time we got here, where did it come from.\" |\n\nBoth end up needing to understand the same code, but they enter it from different ends, and they tend to notice different things.\n\n### Why isolation works\n\nEach teammate has its own context window. A and B share no conversation history. All communication goes through the lead. The lead NEVER forwards A's work to B or vice versa. Round 3 isolation is maintained via per-investigator review files (`review-for-A.md`, `review-for-B.md`) that each teammate reads exclusively.\n\n### Why teammates stay alive\n\n- A and B retain full Round 1 investigation context when critiquing C in Round 3. This makes their pushback grounded in *why* they chose their original hypothesis ranking, not just what the review file claims.\n- C retains its synthesis reasoning from Round 2 when reconciling in Round 4.\n\nPersistence is the main reason to use Teams over the fallback.\n\n---\n\n## How to Execute\n\nYou (the lead) orchestrate everything. The exact tool-call sequence is in `references\u002Fagent-teams-workflow.md`. Below is the orchestration checklist.\n\n### Step 0 — Gather context and detect inputs\n\n**0A. Empty-args short-circuit.** If invoked without `--output-dir`, without `--env`, or without a problem statement on disk, stop immediately. Respond:\n\n> \"This skill requires a problem statement at {output-dir}\u002Fproblem-statement.md and the --env flag. Provide --output-dir and --env (one of `prod` | `dev`), and ensure problem-statement.md exists.\"\n\nDo NOT attempt to investigate without these inputs.\n\n**0B. Read inputs from `{output_dir}`:**\n\n- `problem-statement.md` — required\n- `repro.md` — if present, included in investigators' input. If absent, investigators must work from the problem statement alone.\n\n**0C. Read original pipeline artifacts (if `--original-slug` provided):**\n\nRead-only context from `.dev\u002Fproposals\u002F{original-slug}\u002F`:\n- `final-plan.md` — what the feature was supposed to do\n- `implementation.md` — what was actually built (exact diffs)\n- `coder-report.md` — what was committed and what tests ran\n\nThese are **context, not suspects.** The investigators read them to understand what was built, not as a list of likely causes.\n\n**0D. Confirm `--env`:**\n\n`prod` or `dev`. The env affects investigator tooling guidance:\n- **dev**: investigators may run code locally, add temporary logging, query dev DB, step through. Active investigation.\n- **prod**: investigators are observational — read logs, query telemetry, read code. They may NOT run code in production. Passive investigation.\n\n**Hybrid case (prod bug reproducible in dev).** If `--env prod` was passed but `repro.md` classifies the bug as REPRODUCED or PARTIALLY REPRODUCED in dev, dev-mode investigation IS permitted to test hypotheses about the prod bug. Investigators must explicitly record any dev-bridging in their evidence chain (e.g., \"verified hypothesis H2 by reproducing in dev — dev\u002Fprod parity confirmed for {component}\"). The diagnosis must still answer for prod.\n\nThe skill is agnostic about specific tools. The runtime composes Railway-aware skills, Playwright, log scrapers, etc., based on what's available.\n\n**0E. Exploration budget.** Before spawning A and B, the lead reads **at most 3–5 files** to orient. The investigators re-read source independently — that's the point. Over-exploration in the lead burns context that A\u002FB will duplicate anyway.\n\n**0F. Evidence floor (early bail-out).** Before spawning teammates, confirm at least one of these is present:\n\n- `repro.md` exists and classifies as REPRODUCED or PARTIALLY REPRODUCED\n- `--original-slug` is provided (gives access to feature artifacts as context)\n- The problem statement contains concrete telemetry references (logs, error tracking IDs, stack traces, response bodies)\n\nIf none are present (only a vague problem statement), surface to the user before spawning teammates:\n\n> \"No reproduction, no original-pipeline context, and no telemetry references in the problem statement. Investigation will likely return INSUFFICIENT EVIDENCE. Recommend running fix-reproducer first or gathering data before proceeding. Continue anyway?\"\n\nWait for explicit user confirmation. This avoids burning Teams budget on a structurally guaranteed INSUFFICIENT EVIDENCE outcome.\n\n### Step 1 — Team setup\n\n```\nTeamCreate(team_name=\"inv-\u003Cshort-slug>\", description=\u003Cshort>)\n# Create 5 tasks (A, B, C, critique, reconcile) with dependency chain\n```\n\nDetails in `references\u002Fagent-teams-workflow.md` §\"Round 0\".\n\n### Step 2 — Round 1: Spawn A and B in parallel (same turn)\n\nTwo `Agent(team_name=..., name=\"investigator-a\", ...)` calls in a single message. Each prompt embeds the **investigator role** (`agents\u002Finvestigator.md`), the **investigation format** (`references\u002Finvestigation-format.md`), the assigned strategy, the **isolation rule** (see below), the **env mode** (prod or dev), and explicit **\"wait, don't exit\"** instructions.\n\n**Investigator A prompt must include:**\n- Full content of `problem-statement.md`\n- Full content of `repro.md` (if present)\n- Original pipeline artifacts (if `--original-slug`) marked clearly as CONTEXT, NOT SUSPECTS\n- Investigator role (from `agents\u002Finvestigator.md`)\n- Strategy assignment: **Forward-from-trigger**\n- Env mode and what investigation is permitted\n- Output path: `{output_dir}\u002Finvestigation-A.md`\n- Isolation rule: do NOT read investigation-B.md or any other investigation files\n- Anti-anchoring requirement: must list ≥2 alternative hypotheses even if a leading candidate exists\n- Symptom-confirmation challenge: must explicitly answer \"could the visible error be a symptom of a deeper cause?\"\n\n**Investigator B prompt must include:**\n- Same problem statement, repro, and original-pipeline context\n- Same role file\n- Strategy assignment: **Backward-from-failure-point**\n- Same env mode, output path differing (`investigation-B.md`), same isolation rule, same anti-bias requirements\n\nThen the lead idles — teammate \"done\" messages arrive as new conversation turns. No polling.\n\n### Step 3 — Gates after Round 1\n\n**Artifact gate (required, run first)**: verify on disk that `investigation-A.md` and `investigation-B.md` both exist and are non-empty. If either is missing or empty, `SendMessage(to=\"investigator-a|b\", message=\"Your investigation file at {path} is missing or empty. Write your full investigation to that path before signaling done.\")`. Do not proceed to the quality gate until both files exist on disk.\n\n**Quality gate**: each investigation has required sections — at least 2 hypotheses (top + alternatives), evidence per hypothesis, explicit symptom-confirmation answer, ≥3 concrete code\u002Flog references. Failure → `SendMessage(to=\"investigator-a|b\", message=\"revise: \u003Cspecific>\")`. Teammate resumes with full context.\n\n**Convergence check**: did A and B independently land on the same top hypothesis with the same evidence? If yes, skip to §\"Convergence path\" in `agent-teams-workflow.md` — spawn C for lightweight review only, no Round 2\u002F3.\n\n**(Interactive) checkpoint 1**: pause for user review of investigation-A\u002FB.\n\n### Step 4 — Round 2: Synthesizer C\n\nSpawn `synthesizer-c` teammate. Prompt embeds `agents\u002Finv-synthesizer.md` and instructs Phase 0 (independent code\u002Fevidence exam) before reading investigations. Produce THREE files.\n\nSynthesizer C is required to:\n\n- Phase 0: read source files and evidence directly, before reading A or B's work\n- Phase 1: read investigation-A and investigation-B\n- Phase 2: cross-verify the highest-evidence hypotheses against the actual code\n- Phase 3: synthesize into investigation-C.md with C's own committed top hypothesis, ranked alternatives, and a tentative convergence-status assessment\n- Phase 4: write isolated review files for A and B (no mention of the other investigator)\n\n### Step 5 — Round 2 artifact gate (required)\n\nBefore Round 3, **verify on disk**:\n- `investigation-C.md` exists\n- `review-for-A.md` exists\n- `review-for-B.md` exists\n\nIf any is missing, `SendMessage(to=\"synthesizer-c\", message=\"\u003Cname the missing file>\")`. Do not proceed with partial artifacts.\n\n**(Interactive) checkpoint 2**: pause for user review of investigation-C.md.\n\n### Step 6 — Round 3: Critique (pinned teammate descriptions)\n\nTwo `SendMessage` calls in one turn, using these exact `description` values:\n- `\"Critic A: Round 3 feedback on investigation-A\"`\n- `\"Critic B: Round 3 feedback on investigation-B\"`\n\nEach message embeds `agents\u002Finv-critic.md` and the per-investigator isolation rule (read ONLY own review file + own investigation). Teammates resume with full Round 1 context.\n\nThe critic role specifically asks each investigator: \"Does C's synthesis fairly represent your evidence? Did C address the alternative hypotheses you ranked highly? If not, do you accept C's ranking, or do you have evidence that contradicts it? Does C's committed top hypothesis explain ALL the evidence, or only the symptom?\"\n\n### Step 7 — Round 4: Reconciliation\n\nWhen both critiques arrive, `SendMessage(to=\"synthesizer-c\", ...)` with both feedback bodies inline and `agents\u002Finv-reconciler.md` embedded.\n\nC produces TWO files:\n\n- `diagnosis.md` — the deliverable\n- `reconciliation-notes.md` — one line per critique: `A: \u003Cpoint> → ACCEPTED\u002FPARTIAL\u002FREJECTED — \u003Creason>` (reduces reconciler-bias blind spot)\n\nC is required to commit to a `convergence_status` in diagnosis.md:\n\n- **CONVERGED** — single root cause identified with high confidence, evidence chain explains all observed symptoms\n- **PARTIALLY CONVERGED** — top hypothesis is supported but meaningful uncertainty remains. diagnosis.md commits to the top hypothesis, flags alternatives, and includes a `required_data` section listing what would resolve the uncertainty.\n- **INSUFFICIENT EVIDENCE** — cannot honestly commit to a cause given current evidence. diagnosis.md documents candidate hypotheses and includes a `required_data` section. The fix-pipeline orchestrator should escalate to the user or trigger data gathering before proceeding to fix-plan.\n\nINSUFFICIENT EVIDENCE is a legitimate output, not a failure. The reconciler is explicitly instructed not to manufacture false convergence under pressure.\n\n### Step 8 — Cleanup\n\n```\nSendMessage(to=\"investigator-a\", message={\"type\": \"shutdown_request\", ...})  # all three in parallel\n# Wait for shutdown acknowledgments (idle notifications)\nTeamDelete()\n```\n\nPresent `diagnosis.md` (+ `reconciliation-notes.md`) to the user.\n\n---\n\n## Isolation Rule (embed verbatim in investigator prompts)\n\n```\nISOLATION RULE — strict.\n\nAllowed reads:\n- Files listed under \"Source files\" in this prompt\n- problem-statement.md and repro.md in the current output directory\n- Files listed under \"Original pipeline context\" (if provided) — READ-ONLY, treat as context not suspects\n\nForbidden reads, in the current output directory:\n- investigation-A.md, investigation-B.md, investigation-C.md  (except your own investigation in Round 3)\n- review-for-A.md, review-for-B.md                            (except your own review in Round 3)\n- diagnosis.md, reconciliation-notes.md\n\nForbidden writes:\n- Any file under .dev\u002Fproposals\u002F{original-slug}\u002F  (read-only context)\n\nWhen you finish, SendMessage the team lead \"team-lead\" with a one-line\nplain-text summary including your committed top hypothesis. Then go idle —\ndo NOT exit. You will be messaged again in Round 3 to critique a synthesis\nof your work.\n```\n\nRound 3 adds: \"Read ONLY review-for-A.md (or review-for-B.md for B) and your own investigation-A.md. Do NOT read investigation-C.md, the other investigator's review, or the other investigator's investigation.\"\n\n---\n\n## diagnosis.md Structure\n\n```markdown\n# Diagnosis — {slug}\n\n## Convergence Status\n{CONVERGED | PARTIALLY CONVERGED | INSUFFICIENT EVIDENCE}\n\n## Environment\n{prod | dev}\n\n## Root Cause\n{For CONVERGED: the committed cause, stated precisely.\n For PARTIALLY CONVERGED: the top hypothesis, with caveats.\n For INSUFFICIENT EVIDENCE: \"No single cause can be committed to with current evidence. See Candidate Causes.\"}\n\n## Evidence Chain\n{For each step in the causal chain: what was observed, where (file:line, log reference, etc.),\n and how it connects to the next step. The chain should explain ALL observed symptoms,\n not just the most prominent one.}\n\n## Hypotheses Considered\n{Audit trail. Each hypothesis: name, evidence for, evidence against, verdict (committed\u002Frejected\u002Fdeferred), reason.}\n\n## Candidate Causes\n{Only present for PARTIALLY CONVERGED and INSUFFICIENT EVIDENCE.\n Each candidate: id, description, evidence supporting, evidence against,\n what makes it more or less likely than the others.}\n\n## Required Data\n{Only present for PARTIALLY CONVERGED and INSUFFICIENT EVIDENCE.\n Structured list of additional data that would distinguish remaining hypotheses:}\n\n```yaml\nrequired_data:\n  - id: D1\n    distinguishes: [hypothesis-2, hypothesis-3]\n    description: \"Production logs from auth service for the 5-minute window around the reported failure timestamp\"\n    source: \"Railway logs \u002F production\"\n    blocking_severity: high\n  - id: D2\n    distinguishes: [hypothesis-1, hypothesis-2]\n    description: \"Whether refresh-token expiry was extended in last deployment\"\n    source: \"Git history \u002F config diff\"\n    blocking_severity: medium\n```\n\n`blocking_severity` is one of `high | medium | low`:\n- `high` — fix-pipeline must not advance to fix-plan without this data\n- `medium` — fix-plan can proceed but should be revisited if this data later contradicts the chosen plan\n- `low` — nice-to-have for completeness; does not gate downstream stages\n\n## Symptom vs Cause Analysis\n{Explicit answer to: was the visible error a symptom of a deeper cause? If yes, what's upstream of where it manifests? If no, why is the visible error itself the cause?}\n\n## Confidence + Blocking Items\nCONFIDENCE: HIGH | MEDIUM | LOW\nBLOCKING_ITEMS: N\n```\n\n---\n\n## Bias Mitigations\n\n**Anchoring bias (investigator latches onto first plausible hypothesis).**\nInvestigator role file requires ≥2 alternative hypotheses, even when a leading candidate exists. Synthesizer role requires evaluating all hypotheses, not just top one.\n\n**Symptom-confirmation bias (investigator chases the visible error).**\nInvestigator role file requires explicit answer to: \"could the visible error be a symptom of a deeper cause? What's upstream of where it manifests?\"\n\n**Recency bias from original pipeline artifacts.**\nOriginal pipeline artifacts are framed as CONTEXT, NOT SUSPECTS in investigator prompts. The investigator role file is explicit: read them to understand what was built, not as a list of likely causes.\n\n**Reconciler bias toward own synthesis.**\nSame mechanism as adversarial-proposal:\n- `agents\u002Finv-reconciler.md` includes steelman \u002F perspective-test guidance\n- `reconciliation-notes.md` (required) forces explicit accept\u002Fpartial\u002Freject for every critique point\n- `--interactive` mode lets user review investigation-C.md before Round 3 critiques\n\n**Forced-convergence bias (reconciler manufactures a cause to look decisive).**\nReconciler role explicitly authorizes INSUFFICIENT EVIDENCE as a legitimate output. The reconciler is instructed not to commit to a cause if the evidence doesn't support it.\n\n---\n\n## Known Tradeoffs\n\n**Lead context pressure.** Orchestration across many rounds can fill the lead's window. Stay disciplined: the lead doesn't re-read source files (the teammates do). The lead reads problem-statement.md, repro.md, the three synthesis artifacts, and the final diagnosis. Everything else is teammate-scoped.\n\n**Strategy pair can mismatch.** If the bug doesn't fit a clear forward-trace\u002Fbackward-trace shape (for example, a timing-dependent issue with no clear \"trigger\" or \"failure point\"), the strategy pair may converge prematurely or both miss the cause. The investigator role includes an escape hatch: \"if the assigned strategy doesn't fit, note why and investigate naturally — but explain your reasoning.\"\n\n**Prod investigation is harder.** Without the ability to run code or add logging, prod investigators rely entirely on existing telemetry. If telemetry is sparse, INSUFFICIENT EVIDENCE will be the honest outcome. The skill does not penalize this — it surfaces it.\n\n---\n\n## Invoking the Skill\n\n### Direct prompt\n\n```\n\u002Fadversarial-investigate \\\n  --output-dir .dev\u002Ffixes\u002Fjwt-refresh-tokens\u002Fauth-token-refresh-race\u002F \\\n  --env prod \\\n  --original-slug jwt-refresh-tokens\n```\n\nFor an interactive run:\n\n```\n\u002Fadversarial-investigate \\\n  --output-dir .dev\u002Ffixes\u002F...\u002F... \\\n  --env dev \\\n  --original-slug ... \\\n  --interactive\n```\n\n### As a Claude Code command\n\n`~\u002F.claude\u002Fcommands\u002Fadversarial-investigate.md`:\n\n```\nRead .claude\u002Fskills\u002Fadversarial-investigate\u002FSKILL.md and\n.claude\u002Fskills\u002Fadversarial-investigate\u002Freferences\u002Fagent-teams-workflow.md,\nthen orchestrate the workflow.\n\nArguments: $ARGUMENTS\n```\n\nIf `$ARGUMENTS` is empty or missing required flags, follow Step 0A (empty-args short-circuit).\n\n---\n\n## Output Directory\n\n```\n{output_dir}\u002F\n├── problem-statement.md         ← Input (from orchestrator)\n├── repro.md                     ← Input (from fix-reproducer, if it ran)\n├── investigation-A.md           ← Round 1: Forward-from-trigger\n├── investigation-B.md           ← Round 1: Backward-from-failure-point\n├── investigation-C.md           ← Round 2: Synthesis (lead-only; absent on convergence)\n├── review-for-A.md              ← Round 2: A's eyes only (absent on convergence)\n├── review-for-B.md              ← Round 2: B's eyes only (absent on convergence)\n├── reconciliation-notes.md      ← Round 4: ACCEPT\u002FPARTIAL\u002FREJECT audit trail (absent on convergence)\n└── diagnosis.md                 ← Round 4: FINAL DELIVERABLE\n```\n\nThe presence or absence of `investigation-C.md` + reviews is the structural signal of which path ran:\n- **Full run**: all files present\n- **Convergence run**: investigation-A\u002FB + diagnosis.md only\n\n---\n\n## Reference Files\n\n| File | When to read | Purpose |\n|---|---|---|\n| `references\u002Fagent-teams-workflow.md` | Before orchestrating | Exact tool-call sequence for all rounds |\n| `references\u002Finvestigation-format.md` | When building investigator\u002Fsynthesizer prompts | Investigation template to embed |\n| `references\u002Fdiagnosis-format.md` | When building reconciler prompts | Final diagnosis template (matches diagnosis.md structure above) |\n| `references\u002Fsubagent-fallback.md` | Only if Teams is unavailable | Task-based fallback with file coordination |\n| `agents\u002Finvestigator.md` | Building A\u002FB prompts | Investigation role + strategy pair + bias mitigations |\n| `agents\u002Finv-synthesizer.md` | Building C's Round 2 prompt | Synthesis role with 3-file output spec + tentative convergence assessment |\n| `agents\u002Finv-critic.md` | Building Round 3 messages | Critique guidance (defend, accept, or counter the synthesis) |\n| `agents\u002Finv-reconciler.md` | Building Round 4 message | Bias-aware reconciliation + diagnosis.md spec + convergence status authorization |\n\n## Agent Roles Summary\n\n| Agent | File | Used in | Purpose |\n|---|---|---|---|\n| Investigator | `agents\u002Finvestigator.md` | Round 1 (A, B) | Independent investigation with assigned strategy + anti-bias requirements |\n| Synthesizer | `agents\u002Finv-synthesizer.md` | Round 2 (C) | Independent exam, synthesis, isolated review files, tentative convergence status |\n| Critic | `agents\u002Finv-critic.md` | Round 3 (A, B) | Review own isolated critique, defend or concede on grounds of evidence |\n| Reconciler | `agents\u002Finv-reconciler.md` | Round 4 (C) | Bias-aware reconciliation + final diagnosis + convergence status (including INSUFFICIENT EVIDENCE) |\n",{"name":5,"description":7},"main","50bb36677eced958128cea262c304bf9ceee4d4e","skills\u002Fadversarial-investigate","https:\u002F\u002Fgithub.com\u002FSirTheOracle\u002Fforge-toolkit","https:\u002F\u002Fgithub.com\u002FSirTheOracle","2026-10-20 00:50:37",{"source":8,"skillName":5,"commands":55,"prompt":65,"zipAvailable":66},[56,59,62],{"tool":57,"command":58},"npx","npx skills add SirTheOracle\u002Fforge-toolkit --skill adversarial-investigate",{"tool":60,"command":61},"bunx","bunx skills add SirTheOracle\u002Fforge-toolkit --skill adversarial-investigate",{"tool":63,"command":64},"pnpm","pnpm dlx skills add SirTheOracle\u002Fforge-toolkit --skill adversarial-investigate","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FSirTheOracle\u002Fforge-toolkit\u002Fblob\u002Fmain\u002Fskills\u002Fadversarial-investigate\u002FSKILL.md",true,[68,74,78,82,86,90,94,98],{"path":69,"resourceType":70,"resourceTypeDesc":71,"sizeBytes":72,"sourceHtmlUrl":73},"agents\u002Finv-critic.md","REFERENCE","参考文档",4024,"https:\u002F\u002Fgithub.com\u002FSirTheOracle\u002Fforge-toolkit\u002Fblob\u002Fmain\u002Fskills\u002Fadversarial-investigate\u002Fagents\u002Finv-critic.md",{"path":75,"resourceType":70,"resourceTypeDesc":71,"sizeBytes":76,"sourceHtmlUrl":77},"agents\u002Finv-reconciler.md",5844,"https:\u002F\u002Fgithub.com\u002FSirTheOracle\u002Fforge-toolkit\u002Fblob\u002Fmain\u002Fskills\u002Fadversarial-investigate\u002Fagents\u002Finv-reconciler.md",{"path":79,"resourceType":70,"resourceTypeDesc":71,"sizeBytes":80,"sourceHtmlUrl":81},"agents\u002Finv-synthesizer.md",7397,"https:\u002F\u002Fgithub.com\u002FSirTheOracle\u002Fforge-toolkit\u002Fblob\u002Fmain\u002Fskills\u002Fadversarial-investigate\u002Fagents\u002Finv-synthesizer.md",{"path":83,"resourceType":70,"resourceTypeDesc":71,"sizeBytes":84,"sourceHtmlUrl":85},"agents\u002Finvestigator.md",6683,"https:\u002F\u002Fgithub.com\u002FSirTheOracle\u002Fforge-toolkit\u002Fblob\u002Fmain\u002Fskills\u002Fadversarial-investigate\u002Fagents\u002Finvestigator.md",{"path":87,"resourceType":70,"resourceTypeDesc":71,"sizeBytes":88,"sourceHtmlUrl":89},"references\u002Fagent-teams-workflow.md",15998,"https:\u002F\u002Fgithub.com\u002FSirTheOracle\u002Fforge-toolkit\u002Fblob\u002Fmain\u002Fskills\u002Fadversarial-investigate\u002Freferences\u002Fagent-teams-workflow.md",{"path":91,"resourceType":70,"resourceTypeDesc":71,"sizeBytes":92,"sourceHtmlUrl":93},"references\u002Fdiagnosis-format.md",6734,"https:\u002F\u002Fgithub.com\u002FSirTheOracle\u002Fforge-toolkit\u002Fblob\u002Fmain\u002Fskills\u002Fadversarial-investigate\u002Freferences\u002Fdiagnosis-format.md",{"path":95,"resourceType":70,"resourceTypeDesc":71,"sizeBytes":96,"sourceHtmlUrl":97},"references\u002Finvestigation-format.md",6709,"https:\u002F\u002Fgithub.com\u002FSirTheOracle\u002Fforge-toolkit\u002Fblob\u002Fmain\u002Fskills\u002Fadversarial-investigate\u002Freferences\u002Finvestigation-format.md",{"path":99,"resourceType":70,"resourceTypeDesc":71,"sizeBytes":100,"sourceHtmlUrl":101},"references\u002Fsubagent-fallback.md",10350,"https:\u002F\u002Fgithub.com\u002FSirTheOracle\u002Fforge-toolkit\u002Fblob\u002Fmain\u002Fskills\u002Fadversarial-investigate\u002Freferences\u002Fsubagent-fallback.md",[103,129,151,171,191,212],{"skillNo":104,"name":105,"nameZh":6,"description":106,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":107,"categories":108,"keywords":109,"publishedAt":43},"01M70FS350DG1MT6NBPYRPBFBQ","forge-orchestrator","tmux-based orchestrator for multi-agent building. Coordinates work across Claude Code and two Codex workers via forge-bridge. Translates user requests into dispatched tasks with structured audit logging. Replaces forge-dispatch, forge-state.yml, and stage-routing-map.yml.","https:\u002F\u002Fgithub.com\u002FSirTheOracle\u002Fforge-toolkit\u002Fblob\u002Fmain\u002Fskills\u002Fforge-orchestrator\u002FSKILL.md",[],[110,111,112,113,114,33,115,116,117,118,119,120,121,122,123,124,125,126,127,128],"forge","orchestrator","forge orchestrator","bridge","map","tasks","across","work","audit","multi-agent","logging","tmux","for","audit logging","workers","stage","with","multi","state",{"skillNo":130,"name":131,"nameZh":6,"description":132,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":133,"categories":134,"keywords":135,"publishedAt":43},"01M70FRYFZC51YWHVNNS3862PY","forge-fix-runner","Drain the GitHub `forge-fix` issue queue through the forge fix pipeline, one service at a time. Tallies actionable issues worst-first, scouts a service into a routing plan (clusters + quick\u002Ffull tiers), gets human approval, then dispatches fixes (quick = dispatched fix-code; full = forge-pipeline), gating every `Closes #N` on per-issue verification. Trigger when the user wants to fix triaged QA issues, \"work the forge-fix queue\", or \"run the fix runner\".","https:\u002F\u002Fgithub.com\u002FSirTheOracle\u002Fforge-toolkit\u002Fblob\u002Fmain\u002Fskills\u002Fforge-fix-runner\u002FSKILL.md",[],[136,36,110,137,138,37,139,140,141,142,143,144,33,145,117,146,147,148,149,150],"runner","forge fix runner","quick","actionable","time","issues","qa","gating","when","verification","plan","human","run","at","issue",{"skillNo":152,"name":153,"nameZh":6,"description":154,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":155,"categories":156,"keywords":157,"publishedAt":43},"01M70FRVVW3JAGQQK3FFR2VYRC","forge-coder","Procedural coding skill. Reads implementation.md, validates diffs against the codebase, applies changes in execution order, runs tests after each commit group, and produces a coder-report.md artifact.","https:\u002F\u002Fgithub.com\u002FSirTheOracle\u002Fforge-toolkit\u002Fblob\u002Fmain\u002Fskills\u002Fforge-coder\u002FSKILL.md",[],[110,158,159,160,161,162,163,164,165,166,167,168,169,170],"forge coder","coder","diffs","tests","execution","commit","changes","artifact","procedural","report","codebase","implementation","coding",{"skillNo":172,"name":173,"nameZh":6,"description":174,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":175,"categories":176,"keywords":177,"publishedAt":43},"01M70FRRYF6E22ECC8AGYYJEQ7","fix-reproducer","Optional first stage of the fix-pipeline. Verifies a reported bug is reproducible and captures deterministic repro steps, environment state, and evidence. Single procedural executor — does not spawn sub-agents and does not diagnose. Branches by environment: dev path runs the bug locally; prod path gathers observational evidence from the deployed environment. Always writes repro.md, even on NOT REPRODUCED. Trigger when the user invokes a fix-pipeline with the reproduce step enabled.","https:\u002F\u002Fgithub.com\u002FSirTheOracle\u002Fforge-toolkit\u002Fblob\u002Fmain\u002Fskills\u002Ffix-reproducer\u002FSKILL.md",[],[38,178,36,179,180,181,182,37,183,184,185,186,187,188,189,144,125,126,128,190],"fix reproducer","deterministic","evidence","executor","diagnose","Reproducible","environment","trigger","branches","dev","single","repro","first",{"skillNo":192,"name":193,"nameZh":6,"description":194,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":195,"categories":196,"keywords":197,"publishedAt":43},"01M70FRN8THYBT2DJVX99XQ3CM","fix-plan-reviewer","Single-agent adversarial reviewer for fix plans. Reads diagnosis.md and fix-plan.md, verifies the plan actually addresses the diagnosed cause, attacks the plan from multiple angles (cause coverage, defense adequacy, scope correctness, regression risk, rollback integrity, test plan integrity, risk honesty), and produces fix-review.md with severity-rated issues. Does NOT propose fixes for the issues — that is the revise mode of adversarial-fix-plan. Does NOT re-investigate the diagnosis. Trigger as the review stage of a fix-pipeline, after adversarial-fix-plan has produced fix-plan.md.","https:\u002F\u002Fgithub.com\u002FSirTheOracle\u002Fforge-toolkit\u002Fblob\u002Fmain\u002Fskills\u002Ffix-plan-reviewer\u002FSKILL.md",[],[198,36,199,146,200,201,202,203,37,204,205,141,206,30,207,208,209,210,211,26],"fix plan reviewer","reviewer","plan reviewer","coverage","scope","regression","re","mode","review","defense","integrity","addresses","revise","attacks",{"skillNo":213,"name":214,"nameZh":6,"description":215,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":216,"categories":217,"keywords":218,"publishedAt":43},"01M70FRHGG6HN0VW483NDKX161","fix-coder","Mechanical single-executor that applies a vetted fix plan to the codebase. Reads fix-plan.md (the Changes, Defenses, and Test Plan sections), translates file-level changes into concrete diffs, applies them, runs the test plan, validates that the bug is no longer reproducible (dev) or that the test exercising the failing path passes (prod), and produces a single fix commit. Stays strictly in scope: does NOT modify the plan, does NOT re-investigate, does NOT touch files outside the plan. Always writes fix-coder-report.md, even on failure. Trigger as the implementation stage of a fix-pipeline, after fix-plan-reviewer has approved fix-plan.md.","https:\u002F\u002Fgithub.com\u002FSirTheOracle\u002Fforge-toolkit\u002Fblob\u002Fmain\u002Fskills\u002Ffix-coder\u002FSKILL.md",[],[36,219,159,181,202,37,204,220,221,160,222,163,199,146,28,223,26,224,183,185],"fix coder","failing","mechanical","files","path","test plan"]