ultra-research

$SKILL_DIR is this skill's directory. The Python helper is scripts/vault.py; prompts are in prompts/. Read each prompt when you reach its stage.

When to use (routing)

Prefer plain claudex:deep-research by default. Use ultra-research only when: the question is high-stakes (policy/financial/factual gravity); the user explicitly asks for dual-model or cross-verified research; or a prior deep-research run on the topic returned mixed/unreliable citation integrity.

Setup

1. Disambiguate like deep-research: if the question is underspecified, ask 2–3

clarifying questions, then proceed; else state one interpretation and proceed. Never block mid-run after this point.

1. Resolve paths and the run id:

   VAULT="$(python3 "$SKILL_DIR/scripts/vault.py" vaultpath)"
   REFINED_QUESTION="$(cat <<'EOF'
<refined question>
EOF
)"
   RUN="$(python3 "$SKILL_DIR/scripts/vault.py" runid --date "$(date +%F)" --question "$REFINED_QUESTION")"
   RUNDIR="$VAULT/$RUN"
   mkdir -p "$RUNDIR"

The question must be passed as one safely quoted shell argument; do not inline it inside double quotes where embedded quotes can break the command.

Stage 1 — independent research (parallel)

• Codex (background): dispatch Agent(subagent_type: codex:codex-rescue) with the

text of prompts/codex-research.md, placeholders filled, including --write and the absolute target $RUNDIR/20-report-codex.md. Prefer background.

• Claude (inline): run claudex:deep-research yourself on the same refined

question. When it finishes, write its verified report to $RUNDIR/10-report-claude.md with the report frontmatter (author-model: claude, note-type: report, degraded: false, tags: [ultra-research, report]).

• Join: poll for the Codex file until ready or the deadline. Resolve the

per-stage timeout via the helper (handles scalar or object codexTimeoutMs):

  # Stage-1 research default: 20 min (1,200,000 ms) unless config overrides it.
  DEADLINE=$(( $(date +%s%3N) + $(python3 "$SKILL_DIR/scripts/vault.py" timeout --stage research) ))
  until python3 "$SKILL_DIR/scripts/vault.py" ready "$RUNDIR/20-report-codex.md"; do
    [ "$(date +%s%3N)" -ge "$DEADLINE" ] && break
    sleep 10
  done
  if ! python3 "$SKILL_DIR/scripts/vault.py" ready "$RUNDIR/20-report-codex.md"; then
    # Execute DEGRADED branch A.
  fi

If the post-loop ready check fails → DEGRADED branch A (below).

Stage 2 — adversarial cross-audit (parallel)

Each report is audited by the OTHER model; auditors are blind to each other.

• Codex audits Claude (background): dispatch codex:codex-rescue --write with

the prompts/audit.md contract + the absolute path $RUNDIR/10-report-claude.md, writing $RUNDIR/30-audit-of-claude-by-codex.md (author-model: codex, audited-report-model: claude).

• Claude audits Codex (inline `Task`): dispatch a Task (general-purpose)

subagent and explicitly instruct it to use WebFetch for every cited URL. Give it the prompts/audit.md contract assembled inline and the path $RUNDIR/20-report-codex.md; it writes $RUNDIR/31-audit-of-codex-by-claude.md (author-model: claude, audited-report-model: codex). Joined by the subagent's return.

• Join Codex audit: recompute the deadline from a fresh clock read and the

Stage-2 audit timeout (default 10 min):

  DEADLINE=$(( $(date +%s%3N) + $(python3 "$SKILL_DIR/scripts/vault.py" timeout --stage audit) ))
  until python3 "$SKILL_DIR/scripts/vault.py" ready "$RUNDIR/30-audit-of-claude-by-codex.md"; do
    [ "$(date +%s%3N)" -ge "$DEADLINE" ] && break
    sleep 10
  done
  if ! python3 "$SKILL_DIR/scripts/vault.py" ready "$RUNDIR/30-audit-of-claude-by-codex.md"; then
    # Execute DEGRADED branch B.
  fi

If the post-loop ready check fails → DEGRADED branch B.

Stage 3 — trust-weighted final synthesis

Dispatch codex:codex-rescue --write with prompts/final-synthesis.md, the four absolute paths filled in. It writes $RUNDIR/90-final-report.md and prints a bullet summary to stdout.

• Poll with a freshly recomputed Stage-3 synthesis timeout (default 10 min):

  DEADLINE=$(( $(date +%s%3N) + $(python3 "$SKILL_DIR/scripts/vault.py" timeout --stage synthesis) ))
  until python3 "$SKILL_DIR/scripts/vault.py" ready "$RUNDIR/90-final-report.md"; do
    [ "$(date +%s%3N)" -ge "$DEADLINE" ] && break
    sleep 10
  done
  if ! python3 "$SKILL_DIR/scripts/vault.py" ready "$RUNDIR/90-final-report.md"; then
    # Execute DEGRADED branch C.
  fi

If the post-loop ready check fails → DEGRADED branch C.

• The file is canonical; the rescue stdout is display-only.

Index + present

• Assemble $RUNDIR/00-index.md from prompts/index.md. Read audit verdicts for

the status table with:

  python3 "$SKILL_DIR/scripts/vault.py" get "$RUNDIR/30-audit-of-claude-by-codex.md" trust-verdict
  python3 "$SKILL_DIR/scripts/vault.py" get "$RUNDIR/30-audit-of-claude-by-codex.md" trust-score
  python3 "$SKILL_DIR/scripts/vault.py" get "$RUNDIR/31-audit-of-codex-by-claude.md" trust-verdict
  python3 "$SKILL_DIR/scripts/vault.py" get "$RUNDIR/31-audit-of-codex-by-claude.md" trust-score

• Present to the user: the bullet summary, the two trust-verdicts, and the vault

path $RUNDIR.

Degraded branches (never hard-fail; always label)

Degraded notes get degraded: true in frontmatter AND a first-line banner: > **⚠️ DEGRADED — single-model run; adversarial cross-audit merit absent.**

• A — no Codex report: do NOT fake adversarial merit. Base the final on Claude's

deep-research report (already deterministically verified). Optionally attach a Claude self-audit ONLY if labeled self-audit — NOT adversarial; equivalent to plain deep-research integrity. Write a degraded 90-final-report.md and a degraded 00-index.md.

• B — Codex audit failed: Claude audits Codex's report normally (adversarial in

that direction) AND self-audits its own report under the explicit self-audit — NOT adversarial; equivalent to plain deep-research integrity label; proceed to Stage 3; mark the run partially degraded.

• C — Codex synthesis failed: Claude writes 90-final-report.md from the four

inputs using the Stage-3 merge algorithm; set both author-model: claude and synthesized-by: claude. Not full DEGRADED (all four inputs exist) — just note the synthesis fallback.

Hard rules

1. Each side's own deterministic citation verification still runs inside its own

report; the cross-audit is an ADDITIONAL adversarial layer.

1. An auditor never audits its own report (except the explicitly-labelled degraded

self-audit, which never counts as adversarial merit).

1. The 90-final-report.md file — not any stdout — is the canonical final report.
2. Always deliver a labeled result; never stop to ask permission mid-run.