research-plan

Research → plan.md + sources file

The orchestrator of a three-skill suite:

• source-triage: find sources and classify access, reach, integrity and grade before reading.
• research-plan (this skill): read what is reachable, then write the plan and the sources file.
• evidence-check: an independent audit that every claim is real and supported.

If a sibling skill is missing, do its steps inline from these summaries. The deterministic checker ships inside this skill: python3 <this skill's folder>/scripts/research_checks.py. It is standard-library Python that runs in your own code sandbox (PDF text needs pypdf; pip install pypdf there if missing). Use it wherever a deterministic check is named. Only if no code execution is available, do those checks by hand and say so.

Outputs (fixed names)

research/<topic-slug>/plan.md
research/<topic-slug>/sources__<topic-slug>__<YYYY-MM-DD>.md   ← human view
research/<topic-slug>/ledger.md                                ← working state, written as you go
research/<topic-slug>/notes/<citekey>.md                       ← per-source notes
research/<topic-slug>/notes/raw/<citekey>.txt                  ← raw full text (API XML/PDF text), verbatim-capable
research/<topic-slug>/claims.json                              ← supported claims + quotes, for checking

• <topic-slug>: 3–6 specific words, lowercase-hyphenated (starch-fructan-engineering-plants).
• Never overwrite an earlier run. Same topic: new dated sources file + changelog entry. New angle: new slug.
• Work in the user's connected folder if there is one, else the working directory. Send both main files at the end.

Modes

• auto (default): no pauses; list your choices at the end. step: stop at each ◆.
• quick: keep 8–15 sources. Full reads of up to 5 top sources; others sections: (abstract + results + discussion). Counter-evidence: max 3 searches. Snowball optional.
• deep: 25+ sources, snowballing, parallel scouts, full reads of all A/B sources.
• update: the user downloaded files or asked to refresh → Phase 6.
• Hard constraints in the request (a rubric that needs 2 book chapters, a word limit, a required database) are requirements, not suggestions. Meet them with verified sources, or say plainly which one is unmet.

Phase 0 — Frame

One message:

• the plan's goal and what it is for (agent / skill / MCP / report / experiment / decision);
• scope, years, depth and mode;
• hard constraints;
• 2–6 MECE axes (non-overlapping sub-questions).

Create a task list: Frame → Triage → Read → Synthesize → Write → Check. If no task tool exists, keep the list at the top of research/<slug>/run-notes.md. ◆ Checkpoint: axes + scope.

Phase 1 — Triage (run source-triage)

Library first → discover → integrity for anything you will name → access + reach → grade / role / ⭐.

The ledger is written as you go. Append each search and each classified source immediately; context can be lost mid-run, and the ledger file is what survives.

In deep mode with subagents, send one scout per axis in parallel. Each scout:

• uses ≤15 tool calls;
• writes notes/<axis>.md with sections Takeaway · Cited findings (with links) · Inferences · Gaps;
• appends its candidates to the ledger.

Without subagents, run the axes in sequence. ◆ Checkpoint: counts by access class + ⭐ shortlist.

Phase 2 — Read

• Read readable/held sources, highest grade first. Prefer raw routes (Europe PMC XML via shell, PDF text) and save the text to notes/raw/<citekey>.txt.
• A WebFetch read is read: full (extracted). Use it for understanding, but claims resting on it get ⚠ extracted and are never "supported" by a quote.
• For long texts, read in chunks until you reach the reference list. Quick mode allows sections: reads; label them.
• Set read on each ledger row: full · sections:<which> · abstract · metadata.
• Per source, notes/<citekey>.md holds:
  • WHY (problem);
  • HOW (method, data);
  • WHAT (findings: numbers copied exactly, with a section/page locator);
  • LIMITS, each tagged author-stated (with locator) or my-inference. Without full text: limits: not assessed (read: abstract).
• When a sentence will carry a claim in the plan, copy a ≥40-character verbatim quote from the raw text into claims.json: {"id","claim","source":"notes/raw/<citekey>.txt","quote","locator"}.
• Never fill a note from memory. "Not in the part I read" is a valid answer.

Phase 3 — Synthesize

• Evidence matrix: sources × themes (supports / contradicts / silent). Group by theme, never source by source.
• Convergence (≥3 agree) · divergence (explain by method, population or time) · silence (<2 sources: a gap).
• Independent count: "4 studies (2 independent)". A shared dataset, cohort, team or trial counts once.
• Counter-evidence pass: for headline findings, search for nulls, failed replications and critiques. Record the terms even when nothing turns up. Quick mode: max 3 searches.
• Negative claims ("no one has done X") carry the searches behind them, bounded by what was searched.
• Contribution check: what can the user do with this plan that they couldn't before? Which ⭐ download would change it most?
• Devil's-advocate pass: the strongest counter-argument, cherry-picking, and an unquestioned premise. Don't drop an objection because it is inconvenient.

Phase 4 — Write the files

plan.md

• Header: goal · what it's for · scope · date · link to the sources file · Evidence base: N full (raw) · N full (extracted) · N sections · N abstract · N metadata.
• Body: whatever the request needs.
• Citations: <sup>[3](sources__<slug>__<date>.md#s3)</sup>, numbered in order of first use.
• Flags after a citation:
  • ⚠ abstract-only: only the abstract was read;
  • ⚠ metadata-only: only title/venue known;
  • ⚠ extracted: read via WebFetch, so no verbatim check is possible;
  • ⚠ preprint.
• Close with: Open questions · What the ⭐ downloads would unlock · Unmet constraints (if any) · Changelog.

sources____.md

# Sources — <Readable topic title> (<date>)
Plan: [plan.md](./plan.md) · Question: <one line> · Mode: <quick|deep> · Searched: <databases + dates>
Counts: N total · ⭐ X · readable R · free-but-blocked B · paywalled P · non-paper W · excluded E     (total = every ledger row)
Evidence base: <same breakdown as plan.md>

## ⭐ 1. Download these for local context
| # | Source | Type | Grade | Access · Licence | Why it matters for <what's being built> | How to get it | Save as | Redistribute |

## 2. Open & readable (distilled into the plan)
### <Theme A>
<a id="s1"></a>**[1]** Authors (Year). [Title](URL). *Venue / Book title, pages*. [DOI](https://doi.org/…) — `gold · CC-BY` · `readable:europepmc-xml` · read: full · Grade A · evidence
(a preprint adds a `` `preprint` `` label to this line; the checker then requires `⚠ preprint` on its citations)
- WHY … · HOW … · WHAT … · LIMITS …

## 3. Free but blocked for AI agents (open these yourself)
Entry + the block observed + direct link + any green copy.

## 4. Paywalled
Entry + green-copy link or "none found" + the abstract-level takeaway, if used.

## 5. Non-paper sources
By kind, tier T1–T5. Grey literature: URL + accessed date + snapshot link.

## 6. Excluded (and why)
One bullet per excluded record, starting **Excluded:** <reason>.

## 7. Search log & access-route report

Rules:

• Every entry has an <a id="sN"> anchor matching the plan's numbering.
• Every URL is a [text](url) link, including in the header lines.
• ⭐ rows point at the main entry number.
• Group by access class, then by theme.

Phase 5 — Check, then deliver

1. Deterministic checks: run python3 <this skill's folder>/scripts/research_checks.py all research/<slug>/. Fix every error (missing anchors, missing ⚠ flags, count mismatches, vocabulary, quotes not in source) and re-run until it passes.
2. Evidence check: run evidence-check.
   • With subagents: in a fresh one, given only the files.
   • Without: a same-session check that re-reads every file from disk and uses no memory of writing them. Label it same-session (not independent) and suggest the user run evidence-check in a new chat before relying on it.
3. Spot-open 3 links per access class. A 403/429 from a publisher proves nothing; say so.

Deliver both files with one line on:

• the plan's headline;
• the ⭐ count;
• how many sources need manual download;
• unmet constraints.

In auto mode, also list your choices (axes, years, databases, filters, caps).

Phase 6 — Update (after the user downloads)

1. Match files in the folder to Save-as names.
2. Validate them (python3 <this skill's folder>/scripts/research_checks.py pdf <files>).
3. Read each one, save its raw text, and set held: user and read: full.
4. Re-grade, removing provisional ? grades.
5. Turn ⚠ flags into supported claims with quotes, or rewrite the claims the new text contradicts.
6. Re-run Phase 5 on the changed sections.
7. Write a new dated sources file and add a changelog entry.

Red flags

Thought	Reality
"I'll check access after reading"	Triage first, or paywalled abstracts quietly shape the plan.
"It's OA, so I can read it"	Test the route. OA articles were blocked in testing.
"WebFetch gave me the text"	It gave a model's extraction. Use it for reading, never for quotes.
"I know this paper / chapter"	Trials produced wrong titles, wrong books and a non-existent paper from memory. Look it up first.
"The DOI resolves, so the chapter is right"	Check the book title and pages too.
"Blocked, I'll try a mirror"	Never. Find a legitimate green copy, else list it for the user.
"I'll write the ledger at the end"	A context reset will erase it. Write as you go.
"Three studies agree"	Count independent studies; search for the ones that went the other way.