topic

<objective>

Research AI/ML topic literature. Return actionable findings: SOTA methods, best fit, concrete implementation plan. Skill = orchestrator — gathers codebase context, delegates literature search to researcher agent, packages results into structured report.

NOT for deep single-paper analysis or experiment design — use research:scientist directly for hypothesis generation, ablation design, experiment validation.

</objective>

<inputs>

• $ARGUMENTS: one of:
• <topic> — topic, method name, or problem description (e.g. "object detection for small objects", "efficient transformers", "self-supervised pretraining for medical images")
• plan — produce phased implementation plan from most recent research output (auto-detected from .temp/)
• plan <path-to-output.md> — produce plan from specific existing research output file
• --team — multi-agent mode; spawns 2–3 researcher teammates for topics with 3+ competing method families and no SOTA consensus; ~7× token cost vs single-agent mode

</inputs>

<constants>

HARD_CUTOFF: 900 # 15 min — if researcher does not return, surface partial results from .temp/

Agent calls are synchronous — timeout is handled by Claude Code's native call timeout; no manual extension possible.

Deviation from §8: Agent tool is synchronous; no file-activity poll available; timeout enforced by HARD_CUTOFF only

</constants>

<workflow>

<!-- Agent resolution: see _RESEARCH_SHARED/agent-resolution.md -->

Agent Resolution

# CLAUDE_PLUGIN_ROOT set by Claude Code to installed cache path; plugins/ fallback = source-tree only
_RESEARCH_SHARED=$(python "${CLAUDE_PLUGIN_ROOT:-plugins/research}/bin/resolve_shared.py" 2>/dev/null)  # timeout: 5000

Read $_RESEARCH_SHARED/agent-resolution.md. Contains: foundry check + fallback table. If foundry not installed: use table to substitute each foundry:X with general-purpose. Agents this skill uses: foundry:solution-architect.

Task hygiene: Before creating tasks, call TaskList. For each found task:

• status completed if work clearly done
• status deleted if orphaned / no longer relevant
• keep in_progress only if genuinely continuing

Task tracking: per CLAUDE.md, create tasks (TaskCreate) for each major phase — paper collection, researcher analysis, report generation. Mark in_progress/completed throughout.

Step 1: Understand the codebase context

Read current project before searching, extract constraints:

• Framework (PyTorch, JAX, TensorFlow, scikit-learn)?
• Task (classification, detection, generation, regression)?
• Constraints (latency, memory, dataset size, compute budget)?

Case-insensitive flag/mode normalization — normalize before parsing so --PLAN, --Team, Plan, etc. are accepted:

ARGUMENTS_LOWER=$(echo "$ARGUMENTS" | tr '[:upper:]' '[:lower:]')

Use $ARGUMENTS_LOWER for all flag/mode dispatch checks (--team, --plan, leading plan token); preserve original $ARGUMENTS only where literal substitution into prompts is required (e.g. topic string).

Unsupported flag check — after all supported flags extracted, scan $ARGUMENTS_LOWER for remaining --<token> tokens. If found: print ! Unknown flag(s): \--<token>\. Supported: \--team\. then invoke AskUserQuestion — (a) Abort (stop, re-invoke with correct flags) · (b) Continue ignoring (skip unknown flags, proceed). On Abort: stop.

Early dispatch for --team and plan modes — check BEFORE Steps 2-3 to avoid wasted SOTA search compute:

• If $ARGUMENTS_LOWER starts with plan token (first word is exactly plan) → skip Steps 2-3; jump directly to Plan Mode section below.
• If $ARGUMENTS_LOWER contains --team flag → skip Steps 2-3; jump directly to Team Mode section below.

Steps 2-3 execute only when neither --team nor plan mode is detected.

Step 2: Research & codebase check (run in parallel)

Parallelism scope: 2a (Agent spawn) and 2b (Grep) issue in one response. Any WebSearch/WebFetch calls inside the researcher agent are issued sequentially — invoke all searches before synthesizing results. No mechanism exists to parallelize prose-driven searches across calls.

2a: Spawn researcher agent (issue with 2b simultaneously in one response)

Call Agent(subagent_type="research:scientist", prompt=...). Task researcher: find top 5 papers for $ARGUMENTS, produce comparison table (method, key idea, benchmark results, compute, code availability), recommend single best method given codebase constraints from Step 1 — with brief implementation plan. Agent's own workflow handles research and experiment design details.

Use this prompt scaffold (adapt constraints from Step 1):

Note: pre-compute output paths before spawning — orchestrator must extract branch and evaluate date expressions, then substitute concrete paths into all spawn prompts:

BRANCH=$(git branch --show-current 2>/dev/null | tr '/' '-' || echo 'main') # timeout: 3000
DATE=$(date +%Y-%m-%d)  # timeout: 3000
# Anti-overwrite: resolve counter-suffix before spawn (quality-gates.md rule)
AGENT_OUT=".temp/output-research-agent-$BRANCH-$DATE.md"
_N=2; while [ -e "$AGENT_OUT" ]; do AGENT_OUT=".temp/output-research-agent-$BRANCH-$DATE-$_N.md"; _N=$((_N+1)); done  # timeout: 5000
mkdir -p .temp  # timeout: 3000
# Persist for later bash blocks (Check 41: fresh shell per call)
echo "$BRANCH" > "${TMPDIR:-/tmp}/topic-branch"
echo "$DATE" > "${TMPDIR:-/tmp}/topic-date"

Note: Substitute pre-computed values — do not pass raw $(date) expressions into spawn prompts. Substitute resolved $AGENT_OUT path (not template) so agent writes to correct non-conflicting file.

Research the literature on: <$ARGUMENTS>
Codebase constraints: <framework, Python version, compute budget, existing dependencies from Step 1>
Deliver: comparison table (method, key idea, benchmarks, compute, code available), recommendation for best method, a 3-step implementation plan for this codebase, key hyperparameters (name, typical range, what it controls) for the recommended method, and common gotchas (failure modes and how to avoid them).
Write your full findings (comparison table, paper analysis, recommendation, implementation plan, Confidence block) to `<$AGENT_OUT>` using the Write tool.
Then return ONLY a compact JSON envelope on your final line — nothing else after it:
{"status":"done","papers":N,"recommendation":"<method name>","file":"<$AGENT_OUT>","confidence":0.N}

Health monitoring — Agent tool synchronous; Claude awaits researcher response natively (no Bash checkpoint available). If researcher doesn't return within $HARD_CUTOFF seconds (~15 min), use Read tool to surface partial results from .temp/, continue with what found; mark timed-out agents with ⏱ in report. <!-- Deviation from CLAUDE.md §6: Agent(...) calls are synchronous — no Bash checkpoint/poll available; HARD_CUTOFF constant is sole liveness mechanism. Documented in <constants> block. -->

If Agent tool unavailable (running as subagent where nested spawning blocked), skip Agent call, conduct research inline: use WebSearch and WebFetch to find top 5 papers, synthesize comparison table yourself. Notify user: "Note: researcher agent could not be spawned in this context — conducting research inline."

2b: Check for existing implementations (main context)

Use Grep tool to search codebase for existing related code:

• Pattern: $ARGUMENTS (treat as literal string — if $ARGUMENTS contains regex metacharacters like ., *, +, ?, (, ), [, ], \\, escape them via grep -F semantics, OR escape each metachar with \\ before passing to Grep tool)
• Glob: **/*.py
• Output mode: files_with_matches
• Limit to 1000 results (per external-data.md — never cap at default 10)

Step 3: Report

---
Research — [topic]
Date:        [YYYY-MM-DD]
Scope:       [topic / research question]
Focus:       SOTA literature research
Agents: