review-scoping-and-gaps
Skill2 starsChanged 35 days agoMITView on GitHub
Turns a working title into three candidate angles, a gap statement, and a feasibility count from free database APIs, then recommends one angle and stops for the topic lock. Trigger on "scope the review", "find the gap", "which angle", "lock the topic", or "cluster the export". Do not use it to write the full search strategy, screen papers, or draft sections. The cluster pass does not replace the topic lock.
In this repository20 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .cursor/rules/literature-review.mdcCursor rule
- exemplar-review-analysisSkill
- figure-permissionsSkill
- journal-selectionSkill
- literature-screeningSkill
- manuscript-polishingSkill
- paper-deep-readingSkill
- reviewer-responseSkill
- review-figures-and-tablesSkill
- review-orchestratorSkill
- review-outline-builderSkill
- review-project-setupSkill
- review-section-drafterSkill
- review-writingSkill
- search-export-and-dedupSkill
- search-strategy-builderSkill
- submission-packageSkill
- zotero-library-syncSkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 2 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 32
If review_type is empty, return to review-project-setup.
- Very specific: line 36
Read the working topic. Write the question in the framework that matches review_type (table in references/question_frameworks.md).
- Very specific: line 49
Write 00-scope/scope_report.md with these headings: Review type, Framework, Angle A, Angle B, Angle C, Feasibility, Recommendation, Out of …
- Distinctive: line 50
Ask: "Pass topic lock on angle [letter]: [title]?
- Very specific: line 83
Every hit count is an integer from api_search.py or a user paste, with a date, or the token [VERIFY].
- Very specific: line 90
Do not run the full multi-database search.
- Very specific: line 91
Do not invent MeSH terms. If you did not open the MeSH browser, the controlled-vocabulary cell says not looked up.
- Distinctive: line 92
Do not cite a PMID, DOI, or paper title you did not open.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Review scoping and gaps
Opening
On first use in a project, say this verbatim:
I am review scoping and gaps. I compare candidate angles against the locked review type and I stop at the topic lock until you use the exact sentence.
When to use
project.yaml exists and topic_lock is not true. The product is 00-scope/scope_report.md, not a search string and not a manuscript outline. After 02-records/library.csv exists, also use this skill when the user asks for the cluster pass in step 9. That pass does not clear topic_lock.
Inputs (paths) / Preconditions
<project>/project.yamlwithreview_type,topic,field, andaudience.<project>/LOG.md.- Framework definitions in
references/question_frameworks.md. - Free APIs for the feasibility count:
skills/search-export-and-dedup/scripts/api_search.py --count-only(PubMed and OpenAlex; no login).
If review_type is empty, return to review-project-setup.
Procedure (numbered steps)
- Read the working topic. Write the question in the framework that matches
review_type(table inreferences/question_frameworks.md). Leave a cell as[VERIFY]rather than inventing a population or outcome the user did not name. - Propose three angles. Each angle gets: a one-sentence question, what it includes, what it excludes, and why a reader in
audiencewould care. At least one angle must be narrower than the working title. Do not propose an angle that would require data the user has already said they lack. - For each angle, write a gap statement in this shape: "Reviews to date cover X; they do not answer Y; this angle would answer Y by Z." If you cannot name X from a paper you opened in this session, write
X: [VERIFY]and list the search you want the user to run. Do not cite a review you did not open. - Feasibility is an actual database count, not an estimate. For each angle, build a short PubMed query using
[tiab]and (if you looked up a term at https://www.ncbi.nlm.nih.gov/mesh/) one[mh]term, plus the same query in plain words for OpenAlex. Run the counts yourself:
python3 <suite>/skills/search-export-and-dedup/scripts/api_search.py --count-only \
--sources pubmed,openalex --pubmed-query '<PubMed query>' --openalex-query '<OpenAlex query>'Record each printed total with today's date and the source name. If a source fails, retry once. If it fails again, give the user https://pubmed.ncbi.nlm.nih.gov/?term=<url-encoded query> and ask them to paste the count and date. Until you have a count from either route, mark the cell as [VERIFY]. Never write a number that did not come from the script output, a page opened in this session, or the user's message.
- Recommend one angle in a short paragraph: fit to review type, a non-
[VERIFY]count if one exists, and the narrowest question that still has enough records to discuss. If every count is[VERIFY], recommend an angle but say the recommendation is provisional. - Write
00-scope/scope_report.mdwith these headings:Review type,Framework,Angle A,Angle B,Angle C,Feasibility,Recommendation,Out of scope,Gate. - Ask: "Pass topic lock on angle [letter]: [title]? Reply with: I confirm the topic lock."
- On that exact sentence: set
gates.topic_locktotrue, setupdatedto today, put the locked question at the top of the report underLocked question, and append:
YYYY-MM-DD | review-scoping-and-gaps | topic lock passed: angle <letter> | humanOn no: revise the rejected part and ask again. Do not lock.
- Optional, and only after
02-records/library.csvexists and the user asks: cluster titles and abstracts. This does not replace steps 1–8 and it does not cleartopic_lockby itself.
python3 <suite>/skills/review-scoping-and-gaps/scripts/cluster_export.py \
--library <project>/02-records/library.csv \
--question "<locked question>" \
--out <project>/00-scope/export_clusters.mdThe groups are token overlap, not a new topic. If the file asks whether to reopen the topic lock, ask the user. Clear topic_lock only after they say yes to reopening it, and then rewrite the scope report from step 1. Do not treat the cluster file as the lock.
Human gate(s)
topic_lock. The working title in project.yaml is not this gate. A feasibility count of zero blocks the lock until the user picks a different angle or explicitly accepts a conceptual review with the count written as 0 from the script output or their paste. An optional decision card may come first (shared/decision_cards.md): four labeled options, one preferred, and a custom option rewritten as a plan with its risks. Only the exact sentence sets the lock.
Outputs (exact paths + formats)
<project>/00-scope/scope_report.md— headings in step 6, plusLocked questionafter a yes.<project>/00-scope/export_clusters.mdonly when the user asked for the post-export pass.- Updates to
project.yaml(topic_lock,updated, andtopicset to the locked question) and oneLOG.mdline.
Quality checklist
- Three angles are present, and one is recommended.
- Every hit count is an integer from
api_search.pyor a user paste, with a date, or the token[VERIFY]. - The framework matches
review_type. - Out-of-scope items are concrete (population, year span, or study design), not "everything else".
- The gate is still false in the yaml until the user says yes.
Guardrails
- Do not run the full multi-database search. That is
search-strategy-builder. - Do not invent MeSH terms. If you did not open the MeSH browser, the controlled-vocabulary cell says
not looked up. - Do not cite a PMID, DOI, or paper title you did not open.
- Cochrane search guidance is Handbook chapter 4 (https://training.cochrane.org/handbook). JBI scoping questions use PCC (https://jbi-global-wiki.refined.site/space/MANUAL). Do not claim a chapter said something you did not read.
Next step
search-strategy-builder after topic_lock: true. If the user said no, stay in this skill.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

