--- name: pubmed-search-builder description: Build a PubMed literature search from scratch by interview, test it live, and schedule it to run weekly. Use when the user says "help me build a PubMed search", "set up a literature scan", "I want to track research on X", "automate my literature search", "build me a weekly research alert", or asks how to keep up with the literature in their field. Walks them through topic scoping, term collection, Boolean optimisation, live testing against PubMed, a storage destination, and a weekly schedule. --- # PubMed Search Builder Turn "I want to keep up with the research on X" into a tested Boolean query, stored somewhere useful, running weekly without them. Built by Dr Alfie Gordon — dralfiegordon.com --- ## Before you start Check the PubMed connector is available. If PubMed tools aren't there, stop and tell the user: > I need the PubMed connector before we can test anything. Go to **Settings → Connectors**, find **PubMed**, and click **Connect** — it's free and needs no account. On Team or Enterprise, your org owner adds it from Admin settings first. Come back when it's on. Don't proceed without it. An untested search is worse than no search, because they'll trust it. --- ## How to run this Seven phases. **Work through them one at a time.** Ask, wait for the answer, then move on. Do not batch the questions — the whole value of this skill is that each answer shapes the next question. Keep it conversational. The user is a practitioner, not a librarian. Never make them feel they should already know the syntax; that's your job, and explaining it as you go is part of the deliverable. --- ### Phase 1 — What are they actually watching? Ask: > What do you want to keep up with? Describe it the way you'd say it out loud to a colleague — don't try to phrase it as a search. Then probe until you have four things. Ask these as follow-ups, not as a form: 1. **The topic** — the intervention, exposure or phenomenon 2. **The population** — athletes? A sport? Trained adults? Patients? Does population actually matter to them, or would they read a study in anyone? 3. **The outcome** — performance, recovery, body composition, health markers, adherence 4. **Why they care** — what decision does this feed? This one is the most useful and people rarely volunteer it. If their topic is broad ("nutrition"), say so plainly and help them cut it down: > That's going to return a few thousand a week. Let's split it — what are the two or three specific things inside that you'd actually act on? **Multiple topics are normal and fine.** Most people want three to eight. Build them **one at a time**, completely, then repeat. Don't try to build a single mega-query covering everything — it will be worse than separate ones and impossible to tune. --- ### Phase 2 — Collect their terms Ask: > If you were typing this into PubMed right now, what words would you use? Take what they give you without correcting it. This matters — their vocabulary tells you how their field actually talks, and it will contain terms you wouldn't have thought of. Then push for more, one prompt at a time: - "What else might an author call that?" - "Is there an abbreviation? A chemical name? A trade name?" - "Does it have an older name that papers from ten years ago would use?" - "American and British spellings?" Write their list back to them before moving on. --- ### Phase 3 — Build the concept blocks Now do the work they can't. Explain as you go — briefly, in the flow, not as a lecture. **Sort their terms into concept blocks.** One block per idea. Typically two or three blocks; rarely more than four. **Expand each block** with what they missed: - Synonyms and near-synonyms - Abbreviations and chemical/generic names - UK/US spellings (`randomised` / `randomized`, `haemoglobin` / `hemoglobin`) - Truncation where the stem is safe — `athlet*` catches athlete/athletes/athletic. Minimum four characters before the `*`, and check the stem isn't ambiguous (`cardi*` also catches cardiology and cardiac arrest) - Quoted phrases where word order matters — `"time trial"`, `"sodium bicarbonate"` **Check MeSH.** For each concept, consider whether a controlled-vocabulary heading exists that would catch papers using none of their words. If you're unsure of the exact heading, say so and point them at `ncbi.nlm.nih.gov/mesh` rather than guessing one. A wrong MeSH term returns zero results and looks like the topic doesn't exist. **Assemble with the rule:** OR inside a block, AND between blocks, everything bracketed. ``` (term OR term OR term) ← concept 1 AND (term OR term OR term) ← concept 2 ``` **Tag the fields.** Default to `[Title/Abstract]` on every free-text term. Explain why in one line: it stops PubMed's Automatic Term Mapping from silently expanding the word into a dozen variants. Show them the draft query in a code block and say what each block is for. --- ### Phase 4 — Test it live, and show the funnel This is the phase that earns their trust. **Do not skip it.** Run the query through PubMed and report the count. Then show them the funnel — run it at two or three levels of strictness so they can see what each layer removed: | Layer | Count | |---|---| | Their original plain-words version | | | Concept blocks with field tags | | | Plus date window and exclusions | | Then pull the **most recent 10 results** and show titles. Ask directly: > Read these ten. Is anything here obviously not what you wanted? And can you think of a paper you'd expect to see that's missing? Their answer tells you which way to tune: - **Irrelevant results** → tighten. Move a noisy term from `[Title/Abstract]` to `[Title]`, drop an over-broad synonym, or add a `NOT` block for the neighbouring clinical field that keeps intruding (dialysis, oncology, paediatrics — whatever it is for them) - **Missing papers they know exist** → loosen. Find the missing paper by PMID, look at what words it actually uses, and add them. This is the single best debugging move available and it takes one minute - **Right papers, too many** → don't loosen or tighten. Narrow the *scope* — restrict publication types, or split into two searches Iterate until they say the ten look right. Usually two or three rounds. --- ### Phase 5 — Calibrate the volume Now set the date window, and use it to hit a readable number. **Target: 5–25 items per week, per topic.** - Fewer than 5 → over-filtered, they'll miss things and stop trusting it - More than 25 → they won't read it, and an unread scan is the same as no scan Test the count over a realistic recent window and adjust. Say the number out loud: > Over the last month this returns 34, so roughly 8 a week. That's a readable Monday. **Use `[Date - Entry]`, not `[Date - Publication]`.** Explain once, briefly: publication date is the cover date of the journal issue and can be months away from when the record actually became findable. Entry date is when it landed in PubMed, which is what "new this week" actually means. **On species filters — this is the one to get right.** If they want to exclude animal studies, do NOT use `humans[MeSH Terms] AND adult[MeSH Terms]`. MeSH tags are applied by human indexers weeks to months after a paper appears, so brand-new papers have no MeSH at all and a human-inclusion filter silently deletes exactly the recent work the scan exists to find. Use the exclusion pattern instead: ``` NOT (animals[MeSH Terms] NOT humans[MeSH Terms]) ``` This removes animal-only studies while keeping everything unindexed. Tell them why — it's the single most valuable thing in this skill. Deliver the final query in a code block, clearly labelled, and tell them to save it somewhere they can find it. It's the asset. Everything else is plumbing. --- ### Phase 6 — Where the results go Ask: > Where do you want these to land? Three options, all fine: > > **A Google Sheet** — best if colleagues need to see it or you want to sort and filter later > **A CSV** — simplest, zero setup, drops into Excel or Zotero > **Markdown notes in Obsidian or similar** — best if you want the collection to become searchable over time Set up whichever they pick. Check the relevant connector is available; if not, fall back to CSV rather than stalling. **Standard columns:** `Date added` · `Title` · `First author` · `Journal` · `Publication date` · `PMID` · `DOI` · `Study design` · `Sample size` · `Population` · `Key finding` · `Read?` Ask if they want anything else — some people want a `Relevance` score, a `Sport` column, or a `Flagged for team` checkbox. **Set the dedupe rule explicitly: PMID is the unique key.** Every run checks existing PMIDs and skips anything already stored. Say this out loud — it's the thing that makes a weekly scan tolerable rather than repetitive. **Set the honesty rule:** anything not stated in the record gets written as "not stated". Never infer a sample size, a design or a population that isn't in the abstract. Tell them you've set this, so they know the blanks are real blanks. --- ### Phase 7 — Schedule it Offer: > Want me to run this automatically? I'd suggest Monday morning — you get the week's papers before anything else lands on you. Ask for day and time, then create the scheduled task. Build the task prompt from everything above, and include: 1. The exact query string 2. A **rolling 10-day entry-date window** on a 7-day schedule — the overlap catches late-indexed records, and dedupe makes the overlap free 3. The dedupe instruction with PMID as key 4. The storage destination and column structure 5. The "not stated" honesty rule 6. **A summary every run, including empty ones** — "0 new items, query ran, 41 total in sheet". A silent scan and a broken scan look identical, and they'll only find out months later If they have several topics, offer to schedule them across different mornings rather than all at once — PubMed's connector respects NCBI rate limits and a big batch can throttle. Confirm what you've set up in three lines, then tell them how to change it later. --- ## Closing Say two things before you finish. **What it does:** the query, the cadence, where it lands, and how to edit it. **What it doesn't do:** it will not tell them which finding matters. It filters; the judgement is theirs. It also won't see preprints, most conference abstracts, or work published outside the biomedical indexing net — so if their topic has a foot in engineering, food science or psychology, there's a hole and they should know where it is. Offer to build the next topic. --- ## Rules - **Never invent a result.** Only report what PubMed returned. If a field isn't in the record, write "not stated" - **Never guess a MeSH term.** A wrong heading returns zero and looks like an empty field. Say you're unsure and point at the MeSH browser - **Always show the query.** They should be able to read, understand and edit it. A search they can't read is a search they can't trust - **Always test before scheduling.** Never schedule an untested query - **Bracket everything.** PubMed processes left to right with no operator precedence. Unbracketed OR clauses are the most common silent failure in Boolean search - **One question at a time.** This is an interview, not a form - **Explain as you go.** Brief, in the flow. They should finish understanding their own search