Refine agent instructions about deep research and cached files

[caufieldjh]

I have found that agents don't have clear expectations about the deep research process:

• They don't know how long to wait, and may consider the process to be stuck if it doesn't return results within some arbitrary time
• They may choose an arbitrary set of citations to extract from the deep research report
• They don't consistently interpret pathophysiological events as a chain, even when the report frames the events in this way.

On a more minor note: agents don't inherently know the filenames of cached references (they may search for "pmid_*" instead of "PMID_"). This is usually self-correcting but slows the process, especially for reference types beyond PMID and DOI.

Some combination of refining the agent instructions in Skill files and updating the deep research prompt should help.

[github-actions]

Summary

This issue identifies gaps in agent instructions during the deep research + curation workflow, specifically in the initiate-new-disorder-creation skill (.claude/skills/initiate-new-disorder-creation/SKILL.md) and the deep research prompt itself. Filed by @caufieldjh on 2026-02-26.

---

Problems Identified

1. Unclear wait-time expectations for deep research

The skill currently says only "may be several minutes, be patient" with no concrete guidance. Agents may prematurely assume the process is hung and abort or retry. The just research-disorder <provider> <name> command produces research/<DISORDER>-deep-research-<provider>.md when complete — but agents don't know the expected time range or failure signals.

2. Arbitrary citation extraction from research reports

After the deep research report is generated, agents pick citations without a clear selection strategy. There is no guidance on how many PMIDs to prioritize, how to rank them, or how to handle citations that lack PMIDs (e.g., DOI-only, preprints, reviews vs. primary research).

3. Pathophysiology not interpreted as a mechanistic chain

Agents don't reliably model pathophysiology steps as an ordered causal chain (e.g., trigger → intermediate mechanism → downstream effect). This likely requires both a change to the deep research prompt template (to explicitly frame events sequentially) and agent instructions to preserve that ordering when populating the YAML.

4. Reference cache filename conventions (minor)

The references_cache/ directory uses uppercase prefixes:

• PMID_<id>.md
• DOI_<normalized>.md
• GEO_<id>.md

Agents searching with lowercase pmid_* miss these files, slowing the workflow. Non-PMID reference types (GEO, DOI, clinicaltrials) are especially error-prone since their patterns aren't documented anywhere in the skill files.

---

Related Issues

• Add more instructions for new agent managers #190 — "Add more instructions for new agent managers": overlapping concern about deep research provider setup and bootstrapping clarity. Still open, assigned to @sujaypatil96.
• Establish parallel-agent workflow guidelines for shared checkout/branch integration #360 — "Establish parallel-agent workflow guidelines": addresses clean workspace and CI discipline for agents; tangentially relevant. Still open.
• Retrospective (Codex): tighten PR review workflow skill + add respond-to-reviewer skill #441 — "Retrospective (Codex): tighten PR review workflow skill + add respond-to-reviewer skill": same pattern of agents lacking structured process discipline — but focused on PR review rather than curation intake.

---

Suggested Fixes

For initiate-new-disorder-creation/SKILL.md:

1. Wait-time guidance: State that just research-disorder typically takes 2–10 minutes; the output file appears at research/<DISORDER>-deep-research-<provider>.md. If the file is absent after 15 minutes, check for error output rather than re-running blindly.

2. Citation selection heuristics: After reading the research report, explicitly fetch citations that appear in the .citations.md companion file (e.g., research/<DISORDER>-deep-research-<provider>.md.citations.md). Prioritize human clinical and primary research papers. Aim for at least 5–8 PMIDs before beginning YAML population.

3. Cached file naming: Add a dedicated section listing the naming conventions:

   references_cache/PMID_<id>.md
   references_cache/DOI_<url-normalized>.md
   references_cache/GEO_<id>.md
   references_cache/clinicaltrials_<NCT>.md
   

   Note that all prefixes are uppercase.

For the deep research prompt:

4. Pathophysiology chain framing: Update the prompt to explicitly ask the research tool to present pathophysiology as an ordered sequence of mechanistic steps (e.g., "describe as a numbered causal chain from initiating trigger to clinical manifestation"). This makes it easier for agents to preserve order in the YAML pathophysiology list.

---

This issue is part of a broader pattern of agent process improvement alongside #190, #360, and #441 — all pointing to the need for more explicit, structured agent instructions as the curation workload scales.