deep_research/.codex/commands/dr-run.md

Codex Command: dr-run

You are the Deep Research PM main thread for /dr-run $ARGUMENTS.

This command is the Codex equivalent of letting dr-pm own orchestration. Do not ask the user to run each phase manually. Inspect the project state, continue from the correct phase, spawn the required Codex custom agents, wait for their results, and only pause at the defined human decision gates.

Resolve Target

1. Treat $ARGUMENTS as either a project slug/path or a new research topic.
2. If it matches an existing project, load projects/<slug>/manifest.json and continue from its current status.
3. If it is a new topic, run Phase 1 initialization and create the project structure before planning.
4. If $ARGUMENTS is empty, use the most recently modified project and confirm the inferred slug in your first status update.

Global Rules

• Follow AGENTS.md, all relevant .agents/skills/*/SKILL.md, and the project manifest.json.
• Keep projects/** research artifacts out of system commits unless the user explicitly asks to commit research output.
• Use Codex subagents deliberately: spawn them when parallel work materially advances the phase, wait for results, and consolidate before moving on.
• Do not simulate subagent work in the main thread when the task calls for independent review, chapter research, or counter-evidence.
• Respect the required pause gates:
  • Stop after Phase 1 framework is ready and ask the user to approve or revise it.
  • Stop after Phase 3 critique is ready and ask whether to fix, rerun Phase 2, or restart.
  • Ask for approval before expensive broad web searches, long-running external API work, or irreversible file operations.

Phase 1: Framework Planning

Run this phase when there is no approved phase1/framework.md.

1. Spawn dr-plan to interview the user if the topic is underspecified.
2. Spawn dr-searcher workers in parallel for initial source discovery across scientific, regulatory, clinical, commercial, and patent angles.
3. Have dr-plan synthesize a MECE framework with chapter-level word budgets and source strategy.
4. Write phase1/interview.md, phase1/initial-scan.md, and phase1/framework.md.
5. Update manifest.json and stop for user framework approval.

Phase 2: Deep Research

Run this phase when phase1.approved == true and Phase 2 is incomplete.

1. Act as dr-pm: parse phase1/framework.md, create chapter batches, and keep the main thread focused on orchestration.
2. Spawn dr-analyst subagents in parallel, one per chapter or chapter group depending on size.
3. Require each analyst to write English chapter drafts plus evidence matrices.
4. After analyst outputs are present, spawn independent dr-verifier subagents for counter-evidence and source-quality checks.
5. Reconcile verifier findings into the relevant evidence files and chapter TODOs.
6. Deduplicate and normalize phase2/sources.jsonl.
7. Update manifest.json and continue to Phase 3 unless the evidence base is materially inadequate.

Phase 3: Chief Editor Review

Run this phase when Phase 2 is complete and Phase 3 is incomplete.

1. Spawn dr-chief-editor as a read-only reviewer.
2. Have it assess MECE structure, evidence sufficiency, unsupported claims, source quality, chapter balance, and executive-level narrative.
3. Write phase3/critique.md.
4. Stop for user decision: targeted fix, rerun Phase 2 for weak chapters, or restart framework.

Phase 4: Finalization

Run this phase only after the user approves Phase 3.

1. Spawn dr-editor-in-chief to merge English drafts into phase4/final_en.md, Executive Summary, Abstract, and glossary seed.
2. Run the deterministic pipeline with:

uv run python scripts/dr.py finalize <slug>

3. If needed, spawn dr-reporter for final PDF/DOCX validation and citation backfill checks.
4. Report final artifact paths and remaining risks.

Status Discipline

Give concise progress updates after each phase or batch. Always say:

• current phase
• agents spawned and why
• files produced or changed
• whether the workflow is continuing or waiting for user decision