review-outline-builder
Skill2 starsChanged 35 days agoMITView on GitHub
Builds a thematic review outline with one claim per section, evidence IDs, planned figures, and a word budget that sums to the target. Use when the user says "make the outline", "outline the review", "section claims", "word budget", or "lock the outline". Do not use to draft prose, choose a journal, invent references, or redraw figures.
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-project-setupSkill
- review-scoping-and-gapsSkill
- 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
11 rules. About 0 are common, 9 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈9
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 35
Stop if the topic lock is not recorded.
- Distinctive: line 39
Read the inputs. List the evidence IDs that are actually in the CSV.
- Distinctive: line 63
Write the global claim and one claim per section.
- Very specific: line 67
Run the checker. Add --checklist <project>/07-outline/systematic_methods_checklist.md when the review is systematic.
- Very specific: line 78
Only after the user locks the outline, change the line to Status: locked, rerun the command with --locked, write the gate using the name in …
- Distinctive: line 94
Every non-structural section has at least one evidence ID that is in the CSV.
- Distinctive: line 97
No section claim states a number, mechanism, or priority that is not in the attached rows.
- Distinctive: line 103
Do not invent DOIs, PMIDs, authors, years, sample sizes, or results.
- Distinctive: line 104
Do not draft paragraphs, captions, or a reference list.
- Distinctive: line 105
Do not copy sentences from papers into the claim lines.
- Distinctive: line 106
Do not mark the outline locked because the checker passed.
≈ “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 outline builder
Opening
On first use in a project, say this verbatim:
I am the review outline builder. I assign each section a claim, evidence ids, and a word budget, including limitations and next questions.
When to use
The evidence table already has the papers that may be cited, and the topic lock has been passed. This skill turns those rows into a section map. It stops before any manuscript sentence is written.
Inputs (paths) / Preconditions
<project>/project.yaml— topic, review type (narrative,systematic,scoping, orumbrella), audience.<project>/LOG.md<project>/evidence/evidence_table.csv— ID columnevidence_id, as named inshared/evidence_table_schema.md. IDs look likeE001(at least three digits).<project>/00-scope/scope_report.md<project>/05-reading/notes for every ID you will attach to a section.<project>/06-exemplars/style_brief.mdwhen that file exists. Use its section lengths as the starting budget, then make the budgets sum to the target.shared/gates.mdandshared/writing_rules.md.
<suite> is the directory that contains this skill. <project> is the review folder created by review-project-setup.
Stop if the topic lock is not recorded. Do not create evidence IDs in this skill.
Procedure (numbered steps)
- Read the inputs. List the evidence IDs that are actually in the CSV. An ID that is only in a reading note and not in the CSV is not citable yet.
- Group the IDs into themes. A theme that rests on one study must say so in its claim. Do not write a synthesis claim for a single row.
- Copy
references/outline_template.mdto<project>/07-outline/outline.md. Delete the format-example claims. Keep this shape, including the hyphen bullets:
- Status: draft
- Review type: narrative
- Target words: 6000
- Date: YYYY-MM-DD
## Global claim
One sentence ending with a period.
## S1. Introduction
- Claim: One sentence ending with a period.
- Evidence IDs: E001, E002
- Word budget: 700
- Figures/tables: none- Set
Review typefromproject.yaml. Systematic, scoping, and umbrella outlines need a section whose title containsMethod(search reporting belongs there; item wording comes from the official PRISMA page you open, not from memory: https://www.prisma-statement.org/prisma-2020). Narrative outlines may omit Methods. Every review type also needs two different sections whose titles containLimitationandNext question. Do not fold either into the conclusion. Each has its own claim and evidence IDs. - When
review_typeis systematic, copyreferences/systematic_methods_checklist.mdto<project>/07-outline/systematic_methods_checklist.md. Keep the registration reminder and the bias-tool lines. A registry ID or a tool name staysnone yetornot chosenuntil you open the official page and replace the source line withRegistry source: verified on YYYY-MM-DD at https://...orOfficial page: verified on YYYY-MM-DD at https://.... RoB 2, ROBINS-I, and QUADAS-2 / QUADAS-3 are for different primary-study designs. AMSTAR 2 appraises systematic reviews, not primary studies. PROSPERO is only for eligible health-related systematic reviews. The checklist states which page to open. Leave pooling out. If the user asks for pooled estimates, setPooling: in scopeandUser asked: yes, add- Pooled estimates: in scopeto the outline, and name that work in a section title. Do not calculate a pooled number here. - Write the global claim and one claim per section. Each claim is a sentence the section will defend, no stronger than its weakest attached row. End each claim with a period.
Evidence IDslists CSV IDs separated by commas.noneis allowed only when the title starts with Acknowledgements, Acknowledgments, Funding, or Author contributions. For each ID on a section, set that evidence row'soutline_sectioncell to the section id (S1,S2, ...). Do not add rows and do not change any other cell.Word budgetis an integer. Abstract, references, and figure legends stay outside the sum. Section budgets must add up toTarget words. Take the target from the style brief when it gives one; otherwise set a body target and record why inLOG.md.Figures/tablesisnoneor a list such asFig. 1, Table 1. ReserveFig. 1for an original overview. Do not plan a copy of a published figure here; that decision belongs to the ledger.- Run the checker. Add
--checklist <project>/07-outline/systematic_methods_checklist.mdwhen the review is systematic.
python3 <suite>/skills/review-outline-builder/scripts/check_outline.py \
<project>/07-outline/outline.md \
--evidence <project>/evidence/evidence_table.csvFix every ERROR line until the command prints OK outline.
- Show the user the global claim, the section titles, the evidence IDs, and the budget sum. Leave
Status: draft. - Only after the user locks the outline, change the line to
Status: locked, rerun the command with--locked, write the gate using the name inshared/gates.md(if that file is absent, useoutline_lock) without deleting otherproject.yamlkeys, and append one line toLOG.md:
YYYY-MM-DD | review-outline-builder | outline lock passed | human
Human gate(s)
Outline lock. If the user refuses, append outline lock refused | human and stop. Do not start review-section-drafter. Changing a locked outline later requires the user to clear that lock in LOG.md first. 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 I confirm the outline lock sets the lock.
Outputs (exact paths + formats)
<project>/07-outline/outline.md— markdown in the bullet shape above, including Limitations and Next questions.<project>/07-outline/systematic_methods_checklist.mdwhen the review is systematic.
Quality checklist
check_outline.py --lockedprintsOK outlineafter the user agrees.- Every non-structural section has at least one evidence ID that is in the CSV.
- The word budgets sum to
Target words. - Limitations and Next questions are separate sections, each with a claim and evidence IDs.
- No section claim states a number, mechanism, or priority that is not in the attached rows.
- Systematic, scoping, and umbrella outlines contain a Methods section.
- A systematic outline's checklist prints no errors, and it contains no pooled number unless the user asked and the outline says pooling is in scope.
Guardrails
- Do not invent DOIs, PMIDs, authors, years, sample sizes, or results.
- Do not draft paragraphs, captions, or a reference list.
- Do not copy sentences from papers into the claim lines. A claim is your one-sentence synthesis, not a quotation.
- Do not mark the outline locked because the checker passed. The checker does not replace the user.
Next step
review-figures-and-tables
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.

