/research

name: research
description: Research docs, papers, or state of the art; provide source-backed recommendations and caveats.

> Before asking, read [User Questions](../../shared/codex-user-questions.md). Waits, plan updates, and test runs follow [Agent Waits](../../shared/native-skill-contract.md#agent-waits), [Plan Updates](../../shared/native-skill-contract.md#plan-updates), and [Sandboxed Test Runs](../../shared/native-skill-contract.md#sandboxed-test-runs).

Research

> Task-size routing follows [Proportional Execution](../../shared/native-skill-contract.md#proportional-execution); this skill's specialized lifecycle and acceptance checks remain authoritative.

Source-backed research for documentation, API migration, paper, or state-of-the-art questions.

Input Schema

{
  "question": "required research question",
  "mode": "docs|sota|paper|methodology|code-fidelity",
  "constraints": [
    "optional codebase, compute, version, or implementation constraints"
  ],
  "done_when": "recommendations are source-backed with caveats and confidence"
}

Workflow

01: Create run directory

Run `create_run.py --skill research` per `../../shared/helper-cli-contract.md`.

02: Define research question, mode, and constraints

Modes:

• `docs`: current API/docs/migration answer.
• `sota`: method comparison and implementation recommendation.
• `paper`: single-paper analysis.
• `methodology`: experiment design, metric, guard, and ablation review.
• `code-fidelity`: compare paper/spec claims against implementation.

03: Gather sources

Write `<run-directory>/sources.md`:

| Source | Type | Date/version | Why reliable | Used for |
| --- | --- | --- | --- | --- |

Source rules:

• Prefer primary docs, papers, specs, release notes, code.
• Use current live sources for volatile docs, dependencies, APIs.
• Mark stale/unavailable source explicitly.
• Never cite secondary summaries for high-impact claims unless independently corroborated.

For `sota`, `paper`, `methodology`, or `code-fidelity`, read and apply `../../shared/specialist-orchestration.md` only when independent expertise improves correctness; otherwise never load it. Write `<run-directory>/specialist-research-plan.md` with context packs for the axes below; planning only here, dispatch is step 04b after codebase mapping when implementation is relevant:

• `web-explorer`: current docs, release notes, API and dependency changes.
• `scientist`: formulas, methodology, metrics, ablations, benchmark claims.
• `solution-architect`: only when user expressly requests that advisory pass or selects the role for implementation fit, API boundaries, or migration shape; it returns a bounded read-only design artifact to the parent/session for next action and acceptance.
• `squeezer`: performance or resource claims.
• `data-steward`: datasets, splits, leakage, reproducibility.
• `challenger`: unsupported recommendation or overconfident source synthesis.

Never send full papers, repositories, or all search results to every specialist. Give each only source excerpts, code files, questions needed for its axis.

04: Map to codebase context when implementation is relevant

Inspect `PLUGIN_ROOT/bin/python PLUGIN_ROOT/shared/collect_diff.py --help`; collect `working-tree` scope into `<run-directory>/baseline`. Run topic scan separately; record unavailable paths/collection failures as evidence gaps.

**Structural context (optional)**: for `sota`/`code-fidelity` questions naming Python module/symbol, also probe codemap-py once: `PLUGIN_ROOT/bin/python PLUGIN_ROOT/shared/codemap_adapter.py context --category analysis [--target <qname>] --out <run-directory>/codemap-context.json`. Per `../../shared/codemap-contract.md`, absence/incompatibility is non-fatal — continue with codebase mapping above. Persist result once here; any specialist context pack planned in step 03 includes `<run-directory>/codemap-context.json`, with added queries only under the contract's bounded `Specialist follow-up queries` rule.

04b: Dispatch planned specialists

When step 03 planned specialists, dispatch that single approved wave now, before step 05, even when step 04 is inapplicable, and join all handoffs before writing `research.md`.

05: Produce `<run-directory>/research.md` with:

• `Question`
• `Constraints`
• `Source Table`
• `Findings`
• `Comparison` for SOTA/method choices
• `Implementation Fit`
• `Risks And Unknowns`
• `Recommendation`
• `Next Checks`

06: For paper/code-fidelity mode, include dimensions:

• `F`: formula/math match
• `H`: hyperparameter parity
• `E`: evaluation protocol
• `N`: notation and naming consistency
• `C`: citation/derivation chain

07: Run review gate

Run `git diff --check -- <run-owned paths>` as argv command, limited to files this run edited or generated for executable validation, so unrelated caller edits never decide the result; with no such paths record that absence instead. Write its combined output to `<run-directory>/review.txt` and retain its exit status as review evidence; never erase nonzero result.

08: Run shared gates and write the validated result artifact

Follow `../../shared/helper-cli-contract.md` and authoritative help. For research-only work, mark lint, format, types, tests inapplicable with concrete reasons; review requires non-empty `research.md`, `sources.md`, clean diff check. Write `RESEARCH_METADATA`, validate as `research`, promote only validated candidate.

Replace explicit skip with relevant command when research includes executable validation.

Fail-Fast Rules

1. Missing question => fail. 2. No primary sources for high-impact/current claims => fail. 3. Recommendation not tied to constraints => fail. 4. Paper/code-fidelity claim without code or source reference => fail. 5. Result artifact missing => fail.

Quality Gates

Required:

• `review`: source table, caveats, `git diff --check` on run-owned paths.

Conditional:

• `tests`: when research includes