deep_research/skills/deep-research/SKILL.md

name, description

name	description
deep-research	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 sources cache <slug> --limit 50 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.
• Key Tier 1-2 sources such as ICH Q9/Q10, EU GMP Annex 1, FDA guidance/warning letters, EMA/NMPA/WHO pages, and pharmacopeia materials should be cached as local Markdown snapshots under phase2/source_cache/ before chapter assembly.
• 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.