SKILL.md
---
name: query-planning
description: Decompose a clinical or research question into targeted sub-queries — concepts, hypotheses, and synonym-expanded search terms — so retrieval is thorough instead of a single naive lookup. Use before searching literature for anything more than a trivial question.
metadata:
type: reference
---
# Query Planning
A hard question asked as one flat search gets a shallow answer. "Does metformin reduce mortality in heart failure with diabetes?" is really three questions — a drug, an outcome, and a population — and each needs its own retrieval. This skill makes the agent *plan the search* before running it, so the evidence it gathers actually spans the question.
## When to use
Before [prisma-search](../prisma-search/SKILL.md), whenever the question contains more than one concept: a drug **and** an outcome, a gene **and** a disease, an intervention **and** a comparator, a population qualifier, or a time frame.
## The rule
**Turn the question into a plan before you search: the core concepts, the hypotheses worth testing, and a set of targeted sub-queries with their synonyms.**
Produce four things:
1. **Concepts** — the distinct entities in the question (drug, outcome, population, comparator). Strip filler and generic academic words ("study", "effect", "analysis") so only real concepts remain.
2. **Hypotheses** — the specific claims the search should try to confirm or refute (e.g. "metformin lowers all-cause mortality", "the effect holds in the HF-with-diabetes subgroup").
3. **Sub-queries** — one focused search per concept pairing, not one blob. Retrieve for each, then combine.
4. **Synonym expansion** — for each concept, add the terms a paper might actually use: brand and ingredient names, abbreviations, MeSH-style variants, British/American spellings.
## Doing it well
- **Cover every concept.** If the question names a population or a comparator, a plan that ignores it will miss the studies that matter most.
- **Expand, don't drift.** Synonyms broaden recall; unrelated terms poison it. "MI" for myocardial infarction — yes. A different disease that co-occurs — no.
- **One decomposition, then retrieve per sub-query.** Running the sub-queries separately and pooling the results beats a single over-stuffed query that matches nothing.
- **Fall back gracefully.** If you cannot plan richly, a plain concept split with synonyms still beats the raw question. Never let planning become a blocker.
## Output
```
Question: Does metformin reduce mortality in HF patients with diabetes?
Concepts: metformin | all-cause mortality | heart failure | type 2 diabetes
Hypotheses: (1) metformin lowers all-cause mortality in T2DM
(2) the effect holds in the HF subgroup
Sub-queries: • metformin AND all-cause mortality AND type 2 diabetes
• metformin AND heart failure AND mortality
• metformin AND heart failure (safety / contraindication)
Synonyms: metformin → biguanide, Glucophage
heart failure → HF, cardiac failure, HFrEF, HFpEF
type 2 diabetes → T2DM, NIDDM
```
Retrieve each sub-query, then hand the pooled results to the rest of the pipeline. A planned search finds the subgroup study a flat search would never surface.