/deep-research

description: Deep, multi-source, fact-checked web research with agy — reach for it when a decision or design depends on getting it right and a single-shot answer is not enough (architecture / tool / vendor choices, thorough landscape scans, anything you will act on). Builds an evidence matrix + a plan you approve, then agy browses each angle in parallel while Claude reasons convergence across adaptive rounds (--depth L<=2 / H<=4), runs an agy red-team pass, and returns a cited report with evidence/inference/assumption tags + an applied recommendation. Heavier and slower than /agy:research (single-shot) — use it when depth and correctness matter more than speed.
argument-hint: "[--depth L|H] [--background] [--yes] [--engines agy|mixed] <topic>"
context: fork
allowed-tools: Bash, Write, Read, Workflow

Deep research command. Does **not** replace `/agy:research` (that one is a fast single-shot lookup) — this one drives a multi-round loop through the `deep-research-agy` Workflow: agy browses several angles in parallel per round, Claude judges coverage and convergence between rounds, a red-team pass challenges the central/single-source claims, and only then does synthesis produce the final report.

Raw user request: $ARGUMENTS

Step 1 — Parse + preflight (ONE Bash call)

• `--depth L|H` (default `L`). `H` runs up to 4 rounds instead of 2, red-teams up to 10 claims instead

of 5, and allows longer per-angle timeouts (4m vs 3m) — reserve it for topics that need real convergence (contradictory sources, a recommendation that must survive red-teaming), not quick lookups.

• `--background` runs the Workflow with `run_in_background: true` and **implies `--yes`** (you can't

approve a plan you won't be watching).

• `--yes` skips the plan gate (Step 3) and goes straight to Step 4.
• `--engines agy|mixed` (default `agy`). **`mixed` is currently accepted but behaves identically to

`agy`** — there is no second browsing engine wired in yet. If the user asks what `mixed` does, say this plainly; don't imply real engine diversity that doesn't exist.

• Strip all flags above from `$ARGUMENTS`; what remains, trimmed, is `<topic>`. If empty, ask once:

"What should I deep-research?" and stop.

• Build `SLUG` from `<topic>` (lowercase, non-alphanumeric → `-`, collapse repeats, trim to 60 chars)

and `DATE` = today, ISO `YYYY-MM-DD`.

• `WRITE_FILE` = absolute path to `docs/agy/research/<DATE>-<SLUG>.md`.

`DEEP_DIR` = absolute path to `docs/agy/research/.deep/<DATE>-<SLUG>`.

• One Bash call does the preflight + scaffolding together — agy presence check, then both `mkdir -p`:

  mkdir -p "docs/agy/research/.deep/<DATE>-<SLUG>"
  command -v agy >/dev/null 2>&1 && agy --version || echo "AGY_MISSING"

If the output is `AGY_MISSING`, tell the user to run `/agy:setup` first and **stop** — don't launch a multi-round Workflow (several minutes, several agy calls) against a broken/missing `agy`.

Step 2 — Evidence matrix + angles (Claude reasons, no tool calls)

Decompose `<topic>` yourself into:

1. **Evidence matrix** — rows of `{ id, question, evidenceType, sourceQualityBar, recencyRequirement, contradictionCheck, recommendationChanging }`. `recommendationChanging: true` marks rows whose answer could flip the conclusion — those are the ones convergence and the red-team pass weigh most heavily. 2. **Angles** — `{ label, query, rationale, targetsMatrixIds }`. 3-4 angles at depth `L`, 5-6 at depth `H`. Every angle must target at least one matrix row; every `recommendationChanging` row should be targeted by at least one angle.

Step 3 — Plan gate (skip on `--yes` / `--background`)

Show the user the matrix + angles (a compact table is fine) and wait for an explicit go-ahead or edits. Apply any requested edits and re-show if they were non-trivial. Only proceed to Step 4 once the user is on board. With `--yes` or `--background`, skip this step entirely.

Step 4 — Launch the Workflow

Workflow({
  scriptPath: "${CLAUDE_PLUGIN_ROOT:-$PWD}/plugins/antigravity/scripts/deep-research-agy.js",
  args: {
    question: <topic>,
    matrix: <matrix from Step 2>,
    angles: <angles from Step 2>,
    depth: "L" | "H",
    engines: "agy" | "mixed",
    deepDir: <DEEP_DIR, absolute>,
    date: <DATE>,
    title: <topic>
  },
  run_in_background: <true if --background, else false>
})

`args` is passed as a JSON **object** (the workflow parses it defensively either way, but always pass an object here). `deepDir` and `title` must be final, absolute/resolved values — never placeholders.

• **If `--background`**: tell the user it's running and mention `DEEP_DIR` (partial per-angle

transcripts land there as the rounds progress), then stop — do not block waiting for it. Steps 5-6 only run once you have the Workflow's result in hand (a follow-up turn, or the user checking back).

• **If not background**: await the result — `{ report, coverage, rounds, converged }`. `report`

already conforms to the report schema and `report.coverage` is pre-populated (deterministic, code-computed inside the workflow) — do not recompute or second-guess it.

Step 5 — Grounding + render (Claude, after the Workflow returns)

• **Grounding** (only when the topic asks to apply the findings to a known local design — e.g.

capataz/brain, or this repo's own architecture): si el tema pide aplicar los hallazgos a un diseño/proyecto local conocido Y tenés herramientas de memoria o búsqueda local disponibles (p.ej. engram, grep del repo), usalas para traer contexto y completar `appliedRecommendation.groundedContext` — este es el único campo que el workflow deja deliberadamente vacío, ya que no tiene acceso a memoria o archivos locales. Si no hay ninguna herramienta de ese tipo disponible, o el tema es investigación general sin nada local contra qué anclar, saltá este sub-paso y dejá `groundedContext` tal como lo devolvió el workflow (vacío).

• **Render** — do not hand-roll the markd