---
name: deep-research
description: Use when a user wants to run Deep Research, create a client-ready research report, analyze supplied audit/material files, compare evidence against regulations or best practices, or continue a phase-based research project.
---

# Deep Research

## Principle

Deep Research is driven by the repository Python core, not by chat context. Treat Codex, OpenCode, Claude Code, Antigravity, and Gemini CLI as surface interfaces that call `scripts/dr.py`; all durable state must be written under `projects/<slug>/`.

## Required Flow

1. Work from the repository root.
2. Validate the skill/runtime registry before a serious run:
   `uv run python scripts/dr.py skills validate`
3. For user-supplied materials, stop after Phase 0/1 material brief and interview:
   `uv run python scripts/dr.py init "<topic>" --slug <slug> --method <method> --input-material <path>`
   Review `phase1/material_brief.md` with the user before generating or approving the framework.
4. If model calls will be used, probe the selected profile first:
   `uv run python scripts/dr.py models --profile medium --probe`
5. Run Phase 1 and pause for framework review:
   `uv run python scripts/dr.py frame <slug> --method <method>`
   After user approval: `uv run python scripts/dr.py approve <slug>`
6. Run Phase 2 with file-backed task cards and packets:
   `uv run python scripts/dr.py research <slug> --workers 6 --execute-packets --allow-search-fallback`
7. Build briefs and chapters only from persisted packets:
   `uv run python scripts/dr.py research <slug> --build-briefs`
   `uv run python scripts/dr.py research <slug> --assemble-chapters --workers 4`
8. Review and finalize through Python:
   `uv run python scripts/dr.py review <slug>`
   `uv run python scripts/dr.py finalize <slug> --report-engine reportlab`

## Research Rules

- Chinese is the formal thinking and writing language by default; English is allowed for search keywords, source titles, abstracts, and raw excerpts.
- Do not invent evidence when model/API access fails. Stop at the last durable artifact and report the exact blocker.
- Phase 2 concurrency must use task cards and packet files, not platform subagents as the default mechanism.
- Search must use the project Python gateway (`scripts/search.py` / `scripts.lib.search_client`) by default. Do not use Tavily MCP, browser MCP, or platform-native web search in subagents unless the user explicitly requests that escape hatch.
- User materials are starting evidence, not final truth. Cross-check against authoritative sources such as NMPA, FDA, EMA, ICH, WHO, pharmacopeias, and recognized best-practice references.
- For GMP/quality/operations diagnosis, prefer `--method gmp_quality_operations_diagnosis`.
- Chapter drafts are not acceptable if they merely summarize principles. Each section must turn evidence into concrete findings, risk implications, and整改动作；otherwise return to Phase 2 enrichment.

## Useful Commands

- Status: `uv run python scripts/dr.py status <slug>`
- List methods: `uv run python scripts/dr.py methods list`
- Show method: `uv run python scripts/dr.py methods show <method>`
- Dry-run task cards: `uv run python scripts/dr.py research <slug> --dry-run`
- Sync adapter skills: `uv run python scripts/dr.py skills sync`

## Common Failures

- If Codex cannot write `~/.codex`, run `uv run python scripts/deploy_adapters.py codex --force` outside sandboxed mode.
- The Codex deploy script does not copy `config.toml` by default; use `--include-config` only when the user explicitly wants the bundled Codex profile.
- If `models --probe` returns subscription/model errors, do not launch packet workers; switch profile/key/provider first.
- If a PDF has little embedded text, Phase 0 should call FireRed OCR. Default endpoint: `http://192.168.50.100:8001`.
- If a subagent asks for MCP/web permissions during research, stop it and reroute the task through `search-gateway`.