agentleFS
Xuzhen-LiXuzhen-Li/literature-review-skills/skills/review-section-drafter/SKILL.md

review-section-drafter

Skill2 starsChanged 35 days agoMITView on GitHub

Drafts one review section at a time from the locked outline and the evidence table, with citation keys and hedging matched to the evidence. Use when the user says "draft the introduction", "draft section", "write the next section", or "hedge this claim". Do not use to polish for a journal, invent references, write the cover letter, or draft a section whose outline claim is not locked.

The file

Show its rules and text

We split this skill into the rules it gives an agent

14 rules. About 0 are common, 6 are distinctive, and 8 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 8

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Stop if the outline is not locked.

    line 31
  2. Distinctive:

    Read only the evidence rows and reading notes named in that header.

    line 48
  3. Very specific:

    Write the prose under ## Prose in paragraphs.

    line 49
  4. Very specific:

    Every ID in the header appears at least once in the prose, and the prose cites no other ID.

    line 76
  5. Distinctive:

    Keep the prose within 10 percent of the outline word budget.

    line 78
  6. Very specific:

    Use the real path and the real budget.

    line 88
  7. Very specific:

    Do not call the draft finished, and do not append draft_complete, until every non-structural section has Status: checked and this command …

    line 95
  8. Very specific:

    If the outline has no Limitations section or no Next questions section, stop and return to review-outline-builder.

    line 104
  9. Very specific:

    No project-level lock. Stop when the checker reports [NEEDS SOURCE], [VERIFY], an unknown ID, or a word count outside the 10 percent band.

    line 108
  10. Distinctive:

    No paragraph states a result from one study as if several studies agreed.

    line 120
  11. Distinctive:

    Do not quote more than a short phrase, and only when the reading note already records the page.

    line 128
  12. Very specific:

    Do not convert citations to a numbered journal style in this skill.

    line 129
  13. Distinctive:

    Do not draft the abstract, cover letter, or response to reviewers here.

    line 130
  14. Very specific:

    Do not treat the draft as finished while Limitations or Next questions are missing or still Status: draft.

    line 131

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Review section drafter

Opening

On first use in a project, say this verbatim:

I am the review section drafter. I draft one section from the locked outline and the evidence table, and I mark a sentence that has no evidence row.

When to use

07-outline/outline.md says Status: locked, and the user has named one section. Draft only that section. A later section waits until this file passes the checker.

Inputs (paths) / Preconditions

  • <project>/07-outline/outline.md — the ## S<n> block you were asked to draft.
  • <project>/evidence/evidence_table.csv and the 05-reading/ note for each ID on that block.
  • <project>/08-figures/figure_ledger.csv when the section names a figure.
  • shared/evidence_table_schema.md, shared/writing_rules.md.

Stop if the outline is not locked. Stop if a named evidence ID is missing from the CSV. Do not add rows to the evidence table here.

Procedure (numbered steps)

  1. Copy the section's claim, evidence IDs, word budget, and figure list into a new file <project>/09-draft/S0N-title-slug.md. N is the outline number zero-padded to two digits. The slug is the title in lowercase ASCII, spaces turned into hyphens. Header, then prose:
# S2. Shared findings

- Outline claim: Two independent lines of evidence agree on the direction of the effect.
- Word budget: 1800
- Evidence IDs: E002, E003
- Status: draft

## Prose
  1. Read only the evidence rows and reading notes named in that header. Do not use a paper that is not on the list. If the section needs another paper, stop and reopen the outline lock. Do not cite it "just this once".
  2. Write the prose under ## Prose in paragraphs. Each paragraph that states a result uses this order:
    1. Topic sentence: the point of the paragraph, hedged to the weakest evidence it needs.
    2. Synthesis: what at least two sources agree on, with both citation keys, unless only one source exists.
    3. Critical comparison: where those sources differ in design, population, or result. If there is only one source, this sentence says it is a single study.
    4. Implication for the section claim. Do not add a new fact in this sentence.
  3. Match the verb to the evidence. This is the same ladder as shared/writing_rules.md. "Rows" means evidence-table rows. The design is the study_design column in shared/evidence_table_schema.md. If that cell is empty, use the design line in the reading note.
LevelWhenWording you may useWording you do not use
EstablishedTwo or more independent direct rows and no conflicting row on that pointis, shows, has been reportedproves, conclusively, it is established
SupportedTwo or more rows, or one systematic-review row, and the limitation is statedindicates, is associated withcauses, leads to
SuggestiveOne primary study, or only indirect rowssuggests, may, one study reportedis known to, clearly
ContestedA conflicting row is in the setstudies disagree, and both ids are citedpicking one side as fact
Backgroundbackground rows onlydefinitions and scopeempirical results
NoneNo rowdo not write the sentence; leave [NEEDS SOURCE]any factual claim

A cross-sectional row does not support causes or leads to. If study_design is empty, write is associated with and [VERIFY design], then resolve it before the checker will pass.

  1. Citation keys, in the prose only, use one of these shapes. The year and the family name come from the evidence row. et al. is for three or more authors; two authors use and; one author stands alone. If the row does not list authors, stop and ask. Do not shorten a name to force the pattern.
(Smith et al., 2020; E014)
(Smith and Lee, 2020; E014)
(Smith, 2020; E014)
(Smith et al., 2020; E014; Lee, 2021; E015)

Every ID in the header appears at least once in the prose, and the prose cites no other ID. A figure mention (Fig. 1) must be an id in the ledger. Do not write "with permission" unless that ledger row is granted.

  1. Keep the prose within 10 percent of the outline word budget. If it cannot be done without cutting a cited result, stop and ask the user to reopen the outline lock. Do not silently change the budget.
  2. Run:
python3 <suite>/skills/review-section-drafter/scripts/check_citations.py \
  <project>/09-draft/S02-shared-findings.md \
  --budget 1800 \
  --evidence <project>/evidence/evidence_table.csv

Use the real path and the real budget. [NEEDS SOURCE] and [VERIFY] fail the command on purpose. Replace the path and budget for the section you drafted.

  1. Set Status: draft to Status: checked only when the command prints OK citations. Append:

YYYY-MM-DD | review-section-drafter | drafted S2 | agent

  1. Show the section to the user. Start the next outline section only if the user does not object. If any marker remains, do not continue.
  2. Do not call the draft finished, and do not append draft_complete, until every non-structural section has Status: checked and this command prints OK draft set:
python3 <suite>/skills/review-section-drafter/scripts/check_citations.py \
  --finish \
  --outline <project>/07-outline/outline.md \
  --drafts <project>/09-draft

If the outline has no Limitations section or no Next questions section, stop and return to review-outline-builder. A missing file for either section is not a finished draft.

Human gate(s)

No project-level lock. Stop when the checker reports [NEEDS SOURCE], [VERIFY], an unknown ID, or a word count outside the 10 percent band. The user decides whether to reopen the outline or drop the sentence.

Outputs (exact paths + formats)

  • <project>/09-draft/S0N-title-slug.md — header bullets plus ## Prose. One section per file.

Examples of the ladder and of a full paragraph are in references/claim_strength.md and references/paragraph_and_citations.md.

Quality checklist

  • The checker prints OK citations for this file.
  • Header IDs and prose IDs are the same set.
  • No paragraph states a result from one study as if several studies agreed.
  • Causal verbs appear only when the row's design supports them.
  • The file does not contain a DOI, PMID, page number, or sample size that is not in the evidence row or its reading note.
  • check_citations.py --finish prints OK draft set before the draft is called complete.

Guardrails

  • Model knowledge is not a source. If you cannot point to a row, the sentence is [NEEDS SOURCE] or it is deleted.
  • Do not quote more than a short phrase, and only when the reading note already records the page. Do not paste abstracts.
  • Do not convert citations to a numbered journal style in this skill. That happens in manuscript-polishing.
  • Do not draft the abstract, cover letter, or response to reviewers here.
  • Do not treat the draft as finished while Limitations or Next questions are missing or still Status: draft.

Next step

The next locked outline section, until every non-structural section has a checked file. Then journal-selection.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.