# sciwrite-manuscript Adopt this skill: https://proskills.md/skills/other/dvdsosa-scientific-writing-skills-skills-sciwrite-manuscript Page: https://proskills.md/skills/other/dvdsosa-scientific-writing-skills-skills-sciwrite-manuscript This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required. ## File: skills/sciwrite-manuscript/SKILL.md size: 8939 sha: 85df5e60ebc3a10f00922ab4790be0356840579a upstream: https://github.com/dvdsosa/scientific-writing-skills/blob/master/skills/sciwrite-manuscript/SKILL.md ````text --- name: sciwrite-manuscript description: > Structure a scientific paper section by section — tables and figures, Results, Methods, Introduction, Discussion, Abstract — following Stanford's Writing in the Sciences. Use this skill whenever someone is writing, drafting, planning, restructuring or reviewing any part of a research paper, journal article, conference paper or thesis chapter: "help me with the introduction", "how do I structure the discussion", "is my abstract missing anything", "my results section is too long", "what order should I write the sections in", "does this table look right", "where should the limitations go". Also use it when someone asks what belongs in a given section, or which verb tense a section takes. Use it together with sciwrite-prose, which handles sentence-level editing once the structure is settled. Do NOT use it for grant proposals or review articles (sciwrite-proposals) or for lay summaries and press material (sciwrite-outreach). --- # Structuring a scientific manuscript A paper is not written in the order it is read. This skill covers what belongs in each section, in what order to build them, and how to tell whether a draft section is doing its job. Answer in whatever language the user writes to you in; course examples stay in their original English. --- ## The writing order Build the manuscript in this sequence. It is not arbitrary — each step makes the next one easy, and skipping ahead is why people find writing painful. 1. **Tables and figures.** Not shells or rough drafts: a finished, polished set. They contain the story of the paper, and until you know what that story is you cannot frame anything else. 2. **Results.** Falls straight out of the tables and figures. 3. **Methods.** Could be written at any time — it is a play-by-play of what you did — but it sits naturally here. 4. **Introduction.** Written after the story is nailed down, because only then do you know how to frame the question. 5. **Discussion.** The hardest and most open-ended; easier once everything else exists. 6. **Abstract.** Always last. *Abstract* means *to pull out*, and you are pulling from sections that now exist. When someone asks "where do I start", the answer is almost always the tables and figures, even if they came expecting to talk about the introduction. --- ## What each section owes the reader Keep this table in mind; go to `references/sections.md` for the full treatment of whichever section is actually on the table. | Section | Its one job | Shape | Voice | |---|---|---|---| | Tables & figures | carry the story; stand alone | one clear point each, progressing | — | | Results | summarise the tables at a *higher level* | trends and relationships, table cited in parentheses | active | | Methods | be the recipe | subsections; diagrams where possible | passive fine, jargon fine | | Introduction | set up one question | cone: known → unknown → aim → approach | active | | Discussion | answer that question, then broaden | inverted cone: answer → context → limitations → so what | active | | Abstract | stand alone | background → aim → methods → key results → conclusion → implication | active | **Verb tense, one rule for all of them.** Past tense for completed actions — the experiments, the analyses, what you and others found. Present tense for what is still true as the reader reads: *Figure 1 shows*, *the data suggest*, *the findings confirm*. Both appear in the same paragraph routinely. --- ## Reviewing a draft section Read the section against the checks below before doing any sentence-level work — a beautifully edited Results section that recites the table is still wrong. **Results.** Is it reading the table aloud, number by number? That is the signature failure. Does it waste a sentence saying *Table 1 shows the characteristics of the groups* instead of launching into the finding? Does it justify statistical choices that belong in Methods, or interpret findings that belong in Discussion? Is the treatment-versus-control comparison foregrounded? Are negative results reported? **Methods.** Could someone replicate this? Is it broken into subsections a skimmer can navigate? Is there a protocol or flow that would be clearer as a diagram or table? Is the ethics statement present, if needed? **Introduction.** Count the paragraphs — more than five means it has drifted into a literature review. Is there an explicit statement of aim or hypothesis, in findable words? Does it review the *specific link* being studied, or the two topics separately? Does it summarise prior work at a high level, or walk through studies one by one? Does it leak results or implications? **Discussion.** Does the first sentence answer the question the introduction asked? Does it start with limitations (it should not)? Does it discuss things that were never measured? Are the limitations specific to *this* study, or boilerplate that would fit any paper? Does the last paragraph restate the finding and leave a take-home message? Does anyone outside the immediate field learn why this matters? **Abstract.** Does it stand alone? Does it carry the implication sentence — the *why should I care* — or stop at the conclusion? Does it use the same explicit aim phrasing as the introduction? Do its numbers match the body? **Tables and figures.** Three horizontal rules and no vertical ones? Units on every variable? Significant figures the measurement actually supports? Acronyms defined inside the table or legend? Does each one make a single clear point? Are significance markers unambiguous about which comparison they refer to? Is the same data presented twice, once as a table and once as a figure? --- ## Tools ```bash # The scripts ship in sciwrite-prose/scripts/. Find that skill wherever it was # installed: plugin, `npx skills add` (project or global), or a manual copy. SCIWRITE=$(for d in "${CLAUDE_PLUGIN_ROOT:-.}/skills" .claude/skills .agents/skills \ ~/.claude/skills ~/.agents/skills; do [ -f "$d/sciwrite-prose/scripts/prose_audit.py" ] && { (cd "$d/sciwrite-prose/scripts" && pwd); break; } done) python "$SCIWRITE/extract_text.py" paper.tex python "$SCIWRITE/extract_text.py" paper.tex --section introduction python "$SCIWRITE/numeric_consistency.py" paper.tex python "$SCIWRITE/keyword_consistency.py" paper.tex ``` If `$SCIWRITE` comes back empty, the sciwrite-prose skill is not installed: do these checks by reading, and tell the user that `npx skills add dvdsosa/scientific-writing-skills` adds the scripts. `extract_text.py` maps the sections of a `.tex`, `.docx` or `.md` file, so you can pull the Discussion without anyone pasting it. Run the consistency checks whenever a whole manuscript is in play: numbers that disagree between abstract and body, or a group renamed between Methods and Results, are what a reviewer notices first and what an author never sees. --- ## Helping someone write a section from scratch Ask for the material before offering structure. For an introduction you need to know what is established, what the gap is, and what they asked — and it is common that the gap has not been articulated yet, in which case that is the real work and the writing is easy afterwards. For a Results section, ask for the tables and figures. If they do not exist yet, say so plainly: writing Results before the figures are settled means writing it twice. Draft in their voice, not a generic one, and follow the prose rules from `sciwrite-prose` as you write — active voice, no throat-clearing, keywords repeated exactly. --- ## Output For a section review: ``` ##
review ### Structure ### Specific fixes ### Consistency ``` When the section is sound, say so and move to prose-level work rather than inventing structural objections. --- ## Reference files | File | Read it when | |---|---| | `references/sections.md` | working on any specific section — the full rules, with worked examples per section | | `references/tables-figures.md` | building or reviewing tables and figures; deciding table vs figure | | `references/worked-examples.md` | you want a model of a good section, or of the same section done badly | | `references/oceanography-sections.md` | the paper reports ocean transports, hydrographic sections or cruise data | For sentence-level editing once the structure holds, use **sciwrite-prose**. For deciding how to spend the writing time in the first place, use **sciwrite-process**. ```` ## File: skills/sciwrite-manuscript/references/oceanography-sections.md size: 5835 sha: 7c7ad799fa073500288cc7fd40416db8c464e431 upstream: https://github.com/dvdsosa/scientific-writing-skills/blob/master/skills/sciwrite-manuscript/references/oceanography-sections.md ```text # Section-level patterns in physical oceanography The course teaches IMRaD with biomedical examples: a trial, a cohort, a dose. Observational oceanography keeps the same skeleton but fills it differently — the "subjects" are cruises and sections, the "intervention" is usually nothing, and the reader's first question is *how confident are you in that number?* **Provenance:** the structural rules come from the course. The example text below was written for this file to show the pattern; no sentence is taken or adapted from a published paper. --- ## What changes, section by section | Section | Biomedical default | Oceanographic equivalent | |---|---|---| | Methods opens with | study design, population | the cruises: dates, ship, section line, station spacing | | The "sample" is | patients enrolled | stations occupied, and the years they were occupied | | Randomisation and blinding | central to validity | absent — validity rests on the inverse model's constraints | | The headline number | effect size with CI | transport in Sv with its uncertainty | | The rival explanation | confounding | aliasing of a seasonal or eddy signal by a one-off snapshot | Everything else — one idea per paragraph, the upshot first, keywords identical across sections — is unchanged. --- ## 1. Methods: the cruise paragraph Reviewers check reproducibility here first. The order that works: 1. **The section.** Where it runs, which line designation (A05, P06), station spacing, and where spacing was tightened. 2. **The cruises.** Dates, ship, and which occupation is new versus reanalysed. 3. **The instruments.** CTD, lowered and shipboard ADCP, with calibration and accuracy figures. 4. **The model.** Layer definitions, the constraints imposed, and — critically — what the reference level is and why. 5. **The uncertainty.** How the error bars were produced. The reference level deserves its own sentence. It is the single assumption a sceptical reader will attack, and burying it inside a list invites the attack. > **Thin.** An inverse box model was applied to the hydrographic data. > > **Reproducible.** We applied an inverse box model with eleven neutral-density > layers, conserving mass overall and within each layer, and referenced the > initial geostrophic velocities to the deepest common level. Layer boundaries > follow [ref, Table 1]. --- ## 2. Results: transports, not tables read aloud The commonest defect in this literature is a Results section that walks the reader down a column of numbers already printed beside it. **Report:** the pattern, its magnitude, whether it exceeds the uncertainty, and where it sits relative to earlier occupations. **Do not report:** every value in the table; the fact that a table exists; the same number in text, table and abstract in three different precisions. > **Recital.** The upper-layer transport was 16.3 ± 1.2 Sv in 2003 and > 17.1 ± 1.4 Sv in 2011 (Table 3). > > **Result.** Upper-layer transport increased by 0.8 Sv between occupations, well > within the combined uncertainty of the two estimates (Table 3). Significant figures travel with the uncertainty. `16.34 ± 1.2 Sv` claims a precision the error bar denies; write `16.3 ± 1.2`. The number in the abstract must be the number in the table. --- ## 3. Discussion: open with the answer, not the caveats A discussion that opens with limitations tells the reader the authors do not believe their own result. Limitations belong after the interpretation, and each one should be paired with what it does and does not affect. The field-specific limitation that must appear: **a hydrographic section is a snapshot.** If the analysis rests on two occupations a decade apart, say plainly that interannual and eddy variability cannot be separated from any trend. A reviewer will raise it; raising it first is cheaper. > **Weak.** Our results should be interpreted with caution because of the limited > number of cruises. > > **Specific.** Two occupations a decade apart cannot separate a trend from > interannual variability. The 0.8 Sv change we report is therefore an upper > bound on any secular signal, not evidence of one. --- ## 4. Introduction: narrow to the gap, do not survey The pull towards a general review of the overturning circulation is strong and should be resisted. The funnel: 1. Why this circulation matters — two or three sentences, not two paragraphs. 2. What repeat sections have established at this latitude. 3. **The gap**: which years are missing, which layer is unconstrained, which disagreement between estimates is unresolved. 4. What this paper does about it. If the introduction could preface any paper about the same basin, it is a review, not an introduction. --- ## 5. Abstract: the numbers a reader will quote For a transport paper the abstract has to carry the headline transports with their uncertainties, the years compared, and the one claim the paper defends. Readers cite abstracts; make the citable numbers correct and identical to the table. Checklist before submission: - [ ] Every number in the abstract appears in the body with the same precision. - [ ] Layer names match the Methods definitions exactly. - [ ] The section line and the years are both stated. - [ ] Any acronym in the abstract is expanded there, not only in the body. --- ## 6. Tables and figures - A **station map** is not optional. Geometry described in prose is geometry the reader reconstructs wrongly. - A **transport table** is read across occupations, so occupations belong in columns and layers in rows. - **Uncertainties belong in the table**, not only in the text. A transport without its error bar is not a result. - Colour scales for velocity sections must be **diverging and centred on zero**, or the reader misreads the sign of the flow. ``` ## File: skills/sciwrite-manuscript/references/sections.md size: 11287 sha: 893e9ccbfa6e246055b0eafe5786549d5b255784 upstream: https://github.com/dvdsosa/scientific-writing-skills/blob/master/skills/sciwrite-manuscript/references/sections.md ```text # The sections, one by one Source: modules 5.2, 5.4, 5.5, 5.7, 5.8. Further reading the course recommends: Thomas Annesley's series in *Clinical Chemistry* (free online, not chemistry- specific), and Mimi Zeiger, *Essentials of Writing Biomedical Research Papers*. --- ## Verb tense — one rule for the whole manuscript **Past tense** for completed actions: the experiments, the analyses, what you found, what other studies found. > *We found that… · The average reaction time was… · Miller et al. found…* **Present tense** for assertions that are still true when the reader reads them: what a table or figure shows, what the data suggest, what you believe. > *Figure 1 shows… · Table 1 gives… · The findings confirm… · The data suggest…* This holds in Methods, Results and Discussion alike. Both tenses routinely appear in one paragraph, and that is correct: > *Information was available for 7,766 smokers. Of these, 1,216 were classified > as hardcore smokers. **Table 1 gives** the characteristics of…* --- ## Results Write this immediately after the tables and figures; it falls straight out of them. **The one big mistake: reading the table aloud.** Because Results follows from the tables, there is a pull to walk the reader through every number in order. That is not what the section is for. > *The mean age of the bad witches was 45 ± 5, and the mean age of the good > witches was 36 ± 6. Gender was similar between the groups with 85 % female in > the bad witches and 83 % female in the good witches…* The reader has the table. Your job is the higher-level summary: point out simple relationships, describe big-picture trends, refer to the table for the detail. > *The witches were on average lean and predominantly female (Table 1). Bad > witches were significantly older, had higher blood pressure, exercised less, > and were more likely to smoke than good witches. More bad witches were > unemployed, but this difference did not reach statistical significance.* Note also what is **not** there: a sentence saying "Table 1 shows the descriptive characteristics of the groups." That is obvious from the table. Launch into the finding and cite the table in parentheses. **Complement rather than repeat.** If a bar graph has no precise numbers, give one or two in the text. If the table gives two means, the text can give the percentage difference — *good witches exercised twice as long as bad witches* rather than restating 60 and 30 minutes. **Do highlight the key numbers.** In a placebo-controlled trial of a blood-pressure drug, the between-group difference in reduction is the number the study exists to produce. That one belongs in the text. **Other rules:** - Negative results matter as much as positive ones. - With a control group, the treatment-versus-control comparison is the one to foreground. - Reserve *significant* for statistical significance. - Do not mix in Methods. Justify the statistical approach in Methods; in Results, say what the models revealed. Authors very often explain their model choice here, and it confuses the reader. - Do not mix in Discussion. Results is what the data show; Discussion is what they mean. - Subsections with informative headings help when results are long. - **Use the active voice.** The fear that every sentence will start with *we* is unfounded here: the participants, the measurements, the models and the data are all available as subjects. --- ## Methods The recipe. Enough for someone else to replicate the study — while minimising how hard that is to read. **What goes in** (varies by field; this is the shape): - Materials: reagents, chemicals, cell lines, hardware — with the specifics that make them reproducible (pH, temperature, doses, versions, part numbers). - Ethics approval, if human or animal subjects. This needs an explicit statement. - Experimental protocol. - How each variable was measured, and with what instrument. - The analysis. Annesley's checklist is a good pass: **who, what, when, where, how and why**. Who maintained the records? What was used? When was it done? Where were things kept? **Three ways to make it readable:** 1. **Subsections with informative headings.** Readers skim Methods hunting for one specific thing; headings let them find it. Real examples: *general approach / biosafety / isolation of the virus / serologic analysis* — or *subjects / experimental protocol / hardware / GPS data processing / wind*. 2. **Cite rather than repeat.** For a well-known method, or one you described in an earlier paper: *as previously described [12]*. 3. **Diagrams and tables.** A participant flow chart conveys instantly what a paragraph of numbers conveys tediously. Complex protocols and dosing schedules are usually better as a diagram or table. This is underused. **Passive voice and jargon are both acceptable here** — this is the one section where the rules relax. What was done matters more than who did it; most readers skim; and the active voice tends to produce a wall of sentences starting with *we*. Mixing passive and active is fine as long as it is not jarring. The active voice is equally acceptable if you prefer it; the choice is yours. --- ## Introduction Easier than people expect, because it has a definable format — and shorter: **typically three paragraphs, never more than five.** **The mistake:** treating it as an exhaustive review of the general topic. You have read a hundred papers and want to use them. That is not what this section is for. **The introduction is shaped around your specific question.** For a study on smoking and breast cancer you do not review breast cancer, and you do not review smoking. You review the potential link between the two, and only studies that addressed that link. This narrowness is what makes it easy to write. **The cone — broad to narrow:** 1. **What's known.** Brief context on your specific topic. 2. **What's unknown.** The gaps and limitations in those previous studies. Why is the question still open? 3. **Your specific question, hypothesis or aim** — stated explicitly, with the words: *we hypothesised that*, *we asked whether*, *our aims were*, *we investigated*. Reviewers scan for exactly this phrasing to find out what the paper is about; make it easy to find. 4. **Enough of your approach** to show how your study fills those gaps — bigger, prospective, a better measure, a population nobody studied. Roughly one paragraph each for known, unknown, and your study, though authors often alternate between known and unknown in the early paragraphs. **Summarise the literature at a high level.** Not *Jones et al. did a case-control study with problems x, y and z, and then Smith et al. did a cross-sectional study with problems a, b and c*. Rather: *of nine studies, two found an association and seven did not*, and then the shared limitations, broadly. **Other rules:** - Three *short* paragraphs, not three long ones. - Write it for a general audience; save technical detail for Methods. - No results, no implications. You are setting the question, not answering it. A two-paragraph example that does everything (BMJ Christmas issue, academic spam): paragraph one is entirely background; then one sentence of unknown — *few studies have focused on academic spam*; then the study — *we investigated the amount, relevance, content, and suppressibility of academic emails*. Note that the four named objectives are the four things the Discussion will answer, in order. --- ## Discussion The inverted cone. The introduction ended with the question; the discussion starts by answering it, then broadens. This section gives you the most freedom and is therefore the hardest, and the best place to show what you can do as a writer. **The shape:** 1. **The answer.** First sentence: *We found that…*, answering the question posed at the end of the introduction. State explicitly whether the findings are novel. 2. **Key secondary findings**, if any. 3. **Context.** Possible mechanisms or pathways. How your results fit the existing literature — confirming, contrasting. 4. **Strengths and limitations.** At least one paragraph. 5. **What's next.** Unanswered questions, what needs confirming. 6. **So what.** Implication, speculation or recommendation. Why should anyone outside your niche care? This is where you make them care. 7. **Conclusion.** Restate the main finding and give a take-home message. Repeating it is deliberate — it is the emphasis. **Do not start with the limitations.** A real discussion opened *This meta-analysis is subject to a number of limitations.* Start with *We found*; bury the limitations several paragraphs down. **Do not travel too far from your data.** Speculation is fine near the end, clearly marked. But the main conclusions must report what you actually found, not what you hoped to find, and you should not spend paragraphs discussing something you did not measure. Waffling because the data did not cooperate is visible from outside. **The limitations paragraph is where good papers separate themselves.** Most authors write generic boilerplate that could apply to any study. What impresses a reviewer is a limitations section that names the concerns *they* were forming as they read: > The mark of a good paper, for me, is when authors have anticipated my > criticisms and concerns… Even if they don't have a good answer for those > limitations, just the fact that they recognize them goes a long way to > improving my confidence in the study. — module 5.7 So: read your own paper as a hostile reviewer, list what you would attack, and address those things specifically. Better still, address them with an analysis — one course example excluded participants on confounding medications and reported that the results held. Discussion length in the course's examples ranges from four to seven paragraphs. --- ## Abstract Write it **last**. *Abstract* means *to pull out*: you are pulling snippets from the finished paper, which is why it is easy once the paper exists. **Throw away any abstract you wrote months ago for a conference.** The pull to reuse it is strong — it is already written, why waste work? But it was drafted before the analysis, tables and story were settled, and it will not fit the final paper. Starting the whole manuscript from it is worse. Bin it and start over. **What goes in:** 1. One sentence of background and motivation. 2. The research aim or question, in the same explicit phrasing as the introduction: *we asked whether*, *we hypothesised that*. 3. A minimal overview of the methods. 4. A few key results, a few important numbers. Not many. 5. A brief conclusion answering the question asked. 6. **One sentence of implication, speculation or recommendation.** Easy to omit and important to keep: it is the *why should I care*, and it is what a journalist or a reader outside your field scans for. Structured abstracts (with mandated subheadings) are easier than free-form ones. Either way, the abstract must stand alone — it is the part most people read, and often the only part. Word limits are where your clutter-cutting skills pay for themselves. ``` ## File: skills/sciwrite-manuscript/references/tables-figures.md size: 7032 sha: 71e37b55fc52f88827cf5b547069a9ffc524305d upstream: https://github.com/dvdsosa/scientific-writing-skills/blob/master/skills/sciwrite-manuscript/references/tables-figures.md ```text # Tables and figures Source: module 5.1. Build these **first**, before any prose. The tables and figures contain the story of the paper; the writing around them is, in a real sense, advertising for them. Editors, reviewers and readers often look at them before reading a word — a reviewer typically skims the abstract, then jumps straight to the data to form their own judgement before reading the authors' interpretation. Two consequences. First, they must **stand alone**: a reader must make sense of them without going back to the text, so every acronym, unit and experimental detail needed to read them lives in the title, legend or footnotes. Second, each one must **make a clear point**, and together they must progress through the story. If you cannot say what a table's point is, it is not ready. Use the fewest that tell the story. Never present the same data as both a table and a figure. --- ## Table or figure? **Figures** for visual impact; trends and patterns; a quick story; showing all the data points rather than summary statistics; showing distribution or range; highlighting the single most important result. **Tables** for precise values, and for many variables at once. A figure does not convey a number to the third decimal. If a figure is turning out complex, that is a signal the data belong in a table. A figure that needs study is a failed figure. --- ## Table format **Title** — identifies the specific point of the table, concisely, and says what statistics to expect: *Descriptive characteristics of the two treatment groups, mean ± SD or n (%)*. Repeat the exact keywords used in the column headings and the main text. **Three horizontal rules. No vertical rules.** One above the column headings, one below them, one below the data. This is the convention in almost every journal. The full-grid table is worth calling out specifically, because it costs more than it looks like it should: > I've reviewed many, many papers over the years. And at some point I noticed > that papers with tables like this, with all the grid lines, tend to have lots > of problems elsewhere in the paper… So when I flip to the tables and I see all > those grid lines, there's a red flag that goes off in my head. I automatically > expect that the paper is going to have other problems. I suspect that other > reviewers and editors have formed the same association. — module 5.1 Alternating row shading is fine and looks professional, as long as the three rules are still the only rules. **Footnotes** — symbol conventions differ by journal (asterisks, superscript letters). Do not guess: open a published paper from the target journal and copy what they do. Use footnotes to say exactly which groups were compared and with what test, and to define acronyms and experimental details. ### The five ways tables look unprofessional 1. **Extra grid lines.** As above. 2. **Misaligned columns.** Especially numbers with decimals. Mixed capitalisation between entries. Sloppiness here reads as sloppiness everywhere. 3. **Too many significant figures.** Statistical software emits BMI to three decimals and people paste it in. Report only as many decimals as the measurement supports — for clinical or physical variables, usually one. 4. **Missing units.** *Exercise: 30* — thirty minutes a day? a week? *Age: 45* — years, presumably, but months if these are infants. Easy to lose when pasting from software output. 5. **Extra columns.** An "overall" column in a two-group comparison dilutes the comparison and can be computed from the other columns anyway. A column of exact p-values, where a star and a footnote would flag significance, does the same. Extra columns detract from the point. **Do not reinvent formatting.** Capitalisation, alignment, italics, footnote symbols: pull a published paper from your target journal and copy it. Reviewers and editors notice tables that look like the journal's own. --- ## Figures ### Three kinds **Primary evidence** — gels, micrographs, photographs, x-rays, pathology slides, oscilloscope captures. These show data quality, and they carry a seeing-is- believing weight that no summary statistic does. Video counts too, and carries it even more strongly. **Graphs** — the data visualised. **Drawings and diagrams** — underused, and powerful. Use them for an experimental setup, a participant or data flow, a causal or cycle relationship, a hypothetical model, or to give readers a picture of something they cannot see. Information that is genuinely visual is tedious in prose and instant in a drawing. In one course example, dog-bite and cat-bite locations went into a body diagram instead of a table, and both key messages — most bites are on the hands, and cat and dog bites differ in location — became visible immediately. ### Legends Every figure needs one, because the figure must stand alone: a brief informative title conveying the main point; the experimental details a reader needs; symbol, line and panel definitions; and the statistical detail — which test, which comparison, what the p-values were. ### Graph types | Type | Use | |---|---| | Line graph | trends over time, dose, age — anything increasing or decreasing | | Bar graph | comparing groups at one time point or dose; easy to read, quick story | | Scatter plot | relationship between two continuous variables; shows every data point | | Histogram | distribution of one variable | | Box plot | distribution and spread across groups | | Survival curve | time-to-event | Scatter plots deserve their reputation: they show all the data, including the variation and non-linearity that summary statistics hide. In the course's example, a scatter plot revealed both that one group had far wider variation than its mean suggested and that the relationship was curved rather than straight — neither visible from a table of means. ### The trend-line warning A superimposed line can manufacture a relationship that is not there. In the course, the same scatter of unrelated x and y was shown twice, once with a downward line and once with an upward line; each time the eye saw a correlation. Remove the lines and there is none. Superimpose a fit only when the relationship genuinely has that shape. ### Making graphs easy to read - Label groups meaningfully instead of using arbitrary symbols. **T** and **C** beat filled circles and open triangles, because the reader never has to look at the legend. - Use colour. The black-and-white photocopy era is over. - Put sample sizes on the bars. Readers want *n* and almost never get it. - Shade bars; leave nothing at low resolution. - If stars mark significance, make it unambiguous which comparison they refer to. Ambiguous stars are the single most common defect in published figures. - Do not add a bar graph summarising data a line graph already shows. Averaging sessions 5–10 into a bar adds nothing that a star on the line graph would not, and it clutters the figure. ``` ## File: skills/sciwrite-manuscript/references/worked-examples.md size: 9728 sha: 7e588db0ed85011d7d33ab7ec5c6e2d0d9db8e7f upstream: https://github.com/dvdsosa/scientific-writing-skills/blob/master/skills/sciwrite-manuscript/references/worked-examples.md ```text # Worked examples, section by section Course examples are marked with their module. Engineering examples were written for this plugin to exercise the same patterns in a different register — the rules are the course's, the sentences are not. --- ## Introduction: the known / unknown / aim skeleton ### Course example — academic spam (module 5.5) Two paragraphs. The whole introduction. > **[known]** *Unsolicited and unwanted (spam) electronic invitations to speak at > or attend conferences or to write for or edit journals are a burgeoning aspect > of academic life. Colleagues regard such invitations with wry amusement, > intense frustration or resignation. Two of us have reviewed travel grant > applications from colleagues who received spam invitations to give conference > presentations.* > > **[unknown]** *Few studies have focused on academic spam.* > > **[this study]** *We investigated the amount, relevance, content, and > suppressibility of academic emails.* The unknown is one sentence. The aim names four things — and those four are exactly what the discussion answers, in order. That correspondence is the point. ### Course example — obesity and cancer mortality (module 5.5) Alternates known and unknown, which is common: - known: excess weight raises all-cause and cardiovascular mortality; it matters in cancer generally - unknown: the magnitude, and which individual cancers - known: consistent associations for endometrium, kidney, gall bladder, breast (post-menopausal), colon in men - unknown: pancreas, prostate, liver, cervix, ovary and blood cancers are scarce or inconsistent — *summarised in a single sentence, with no study-by-study walk* - why the question is open: few prospective studies, inconsistent categorisation of overweight, smoking bias - this study: *We conducted a prospective investigation in a large cohort of U.S. men and women to determine the relations between body mass index and the risk of death from cancer at specific sites.* Every gap named in the "unknown" is answered by a design feature named in the last sentence: prospective, large, BMI rather than arbitrary categories. ### Engineering version > **[known]** *Convolutional detectors now run in real time on embedded > accelerators, and several vendors ship toolchains that quantise and deploy them > automatically [refs].* > > **[unknown]** *How much accuracy that automated quantisation costs is reported > inconsistently: published figures range from under one point to more than eight, > across benchmarks that differ in resolution, class balance and backbone.* > > **[gap in prior work]** *No study has held the deployment target fixed while > varying the backbone, so the reported spread cannot be attributed to the > quantisation itself.* > > **[this study]** *We measured post-quantisation accuracy and latency for three > backbones on a single Kria KV260 target, using one dataset and one toolchain > version, to isolate the cost of automated quantisation.* Note the shape: the gap is not "nobody has done this", it is "the existing numbers cannot answer the question because of how they were produced" — which is what makes the study necessary rather than merely new. --- ## Results: summary versus recitation ### Course example — the witches table (module 5.2) **As written by a student:** > *The characteristics of the bad witches and the good witches are shown in Table > 1. The mean age of the bad witches was 45 ± 5, and the mean age of the good > witches was 36 ± 6. Gender was similar between the groups with 85 % female in > the bad witches and 83 % female in the good witches. The mean BMI of the bad > witches was…* **Edited:** > *The witches were on average lean and predominantly female (Table 1). Bad > witches were significantly older, had higher blood pressure, exercised less, > and were more likely to smoke than good witches. More bad witches were > unemployed, but this difference did not reach statistical significance.* No numbers at all, and nothing is lost — the table has them. The first sentence of the original, announcing what Table 1 contains, is deleted entirely. ### Course example — running during pregnancy (module 5.3) Here some numbers *do* belong, because this table carries the study's main result. The edit keeps four and drops a dozen: > *70 % of runners ran during pregnancy (n = 77), and almost one-third ran during > the third trimester. On average, those who ran during pregnancy greatly > curtailed their training — running just 20.3 ± 9.3 miles per week and cutting > their intensity to about half of their non-pregnant running effort. Three > reported sustaining a running injury while pregnant. In the postpartum period, > nearly a quarter waited two or fewer weeks to resume running, and most resumed > within two months.* Two things to notice. *47.9 ± 21 %* became *about half*, because the precision was not the point. And *3.9 %, 3 out of 77* became *three*, because three is self-evidently a small number. ### Engineering version **Recitation:** > *Table 3 shows the results for the three configurations. The mean latency of > configuration A was 12.4 ± 1.3 ms, the mean latency of configuration B was 9.8 > ± 1.1 ms, and the mean latency of configuration C was 9.6 ± 1.4 ms. The > accuracy of configuration A was 91.2 %, of configuration B 93.7 %, and of > configuration C 93.9 %.* **Summary:** > *Hardware acceleration cut mean latency by roughly a quarter with no loss of > accuracy, and the two accelerated configurations were indistinguishable from > each other (Table 3). The accuracy gap that matters is between the baseline and > either accelerated variant: 2.5 points.* The one number promoted into the text is the one the study exists to estimate. --- ## Discussion: answering the question you asked ### Course example — low-carb versus low-fat (module 5.7) The introduction ended with two questions: (a) greater weight loss on a carb-restricted diet, and (b) without harming heart health. Paragraph 1, first sentence, answers (a): > *We found that severely obese subjects with a high prevalence of diabetes and > pre-diabetes lost more weight in a six-month period on a carb-restricted diet > than on a fat- and calorie-restricted diet.* Paragraph 2 answers (b). Paragraph 4 gives the limitations — and gives them well: many participants were on lipid-lowering and antihypertensive drugs, which could plausibly drive the cardiovascular findings, so the authors re-ran the analysis excluding those participants and reported that the result held. Paragraph 6 adds the high attrition rate. Paragraph 7 restates both answers, then adds the caution that keeps the paper honest: > *This study proves a principle and does not provide clinical guidance. Given > the known benefits of fat restriction, future studies evaluating long-term > cardiovascular outcomes are needed before a carb-restricted diet can be > endorsed.* That last move — refusing to overstate — is what a careful reviewer is looking for. ### How not to open a discussion (module 5.7) > *This meta-analysis is subject to a number of limitations.* Start with what you found. The limitations go several paragraphs down. ### Engineering version, opening paragraph > *We found that automated eight-bit quantisation costs between 1.1 and 2.4 > accuracy points on the KV260, and that the spread across backbones is far > narrower than the published range suggests. The depthwise-separable backbone > lost the most, which we did not anticipate.* *We found that*, then the answer, then an explicit note that one finding was novel or unexpected. Saying which results surprised you is not a weakness; it is the sentence a reader remembers. --- ## Abstract: pulling from the finished paper ### Course example — academic spam (module 5.8), structured - **Background / objectives** — *to assess the amount, relevance, content and suppressibility of academic spam invitations to attend conferences or submit manuscripts* - **Design, setting, participants** — five academics - **Main outcome measures** - **Results** — *at baseline, recipients received an average of 312 spam invitations each month. Unsubscribing reduced the frequency by 39 % after one month, but by only 19 % after one year. Overall, 16 % of spam invitations were duplicates and 83 % had little or no relevance to the recipients. Spam invitations were characterised by inventive language, flattery and exuberance.* - **Conclusion** — *academic spam is common, repetitive, often irrelevant and difficult to avoid or prevent.* The results answer the four objectives in the order they were stated. That alignment is what makes an abstract feel tight. ### The missing sentence most abstracts have The implication. One sentence at the end saying why this matters beyond the study. It is the first thing a journalist or an outside reader looks for, and the easiest thing to leave out because you are already at the word limit. --- ## A whole-manuscript failure mode: numbers that disagree From module 4.6, and worth keeping in mind because it costs nothing to prevent and is expensive to be caught on: - Methods: *we followed participants for a minimum of two years.* - Results: *the average follow-up time was one and a half years.* Both cannot be true. Whatever the author meant, a reviewer now doubts the whole analysis. Same for an abstract that reports different numbers from the body, and for a table and a figure that should match and do not: > If you can't keep track of your dataset, that makes me worry about the whole > analysis. — module 4.6 Run `numeric_consistency.py` before submitting. ``` ## File: README.md upstream: https://github.com/dvdsosa/scientific-writing-skills/blob/master/README.md ````text # Scientific Writing Skills **A Claude plugin for scientific writing** — six AI skills that edit research prose, structure IMRaD manuscripts, run the writing process, handle peer review and publication ethics, draft grant proposals, and translate research for general audiences. Distilled from all eight units of Stanford's [*Writing in the Sciences*](https://online.stanford.edu/courses/som-y0010-writing-sciences) (Kristin Sainani) — 62 lecture transcripts, ~141,000 words — into instructions an AI assistant can actually act on, plus four Python scripts that catch mechanically what a reviewer would catch by eye. Works with [Claude Code](https://claude.com/claude-code), Claude Cowork, and any tool that supports the Claude Agent Skills format. [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23194593.svg)](https://doi.org/10.5281/zenodo.23194593) --- ## What it looks like A paragraph from `examples/`, before and after `sciwrite-prose`: **Before** > As it is well known, the implementation of a hardware acceleration strategy provides a reduction in the inference latency of convolutional neural networks that are deployed on resource-constrained embedded platforms. However, a degradation of the detection accuracy is caused by the quantisation of the network weights to eight-bit integers. Therefore, there is a significant increase in memory pressure when the batch size is raised above four. Furthermore, the results were not inconsistent with those reported for comparable architectures, and the overhead was not significant. Moreover, the proposed pipeline for real-time defect detection, which combines a lightweight backbone with a hardware-accelerated non-maximum suppression stage running on the programmable logic of the Kria KV260, achieves 31 frames per second at 1080p. The DPU IP was integrated into the PL via AXI4, and the PS ran a PetaLinux image with the XRT stack managing DMA transfers between DDR and BRAM. Due to the fact that a majority of the successful solutions rely on this approach, we adopted it. **After** > Hardware acceleration cuts inference latency for convolutional neural networks on resource-constrained embedded platforms, but quantising the weights to eight-bit integers costs detection accuracy, and memory pressure climbs sharply once the batch size passes four. > > Our pipeline pairs a lightweight backbone with hardware-accelerated non-maximum suppression on the programmable logic of the Kria KV260, reaching 31 frames per second at 1080p. The deep-learning processing unit talks to the programmable logic over AXI4, and the processing system runs a PetaLinux image whose runtime moves data between DDR and block RAM. These results agree with those reported for comparable architectures, and the overhead stays small. We chose this design because most published solutions rely on it. | | Before | After | |---|---|---| | Words | 165 | **112** | | Sentences | 7 | 5 | | `to be` verbs per 100 words | 4.8 | **0.0** | | Nominalisations per 100 words | 6.7 | 4.5 | | Defects flagged by `prose_audit.py` | 25 | **4** | Same claims, same numbers, a third shorter. The skill named every one of those 25 defects and said why; the script found them without reading for meaning. It also added no number the author never gave: "the overhead was not significant" stays vague in the rewrite, and the skill asks the author for the figure instead of inventing one. --- ## What it does You paste a paragraph and ask why it feels bloated. It tells you: a smothered verb, a throat-clearing opener, a nominalisation, and a buried predicate — and hands you the rewrite. You ask where to start on a paper. It tells you the tables and figures come first, and why. You get a decision letter that looks like a rejection. It tells you that "revise and resubmit" is the outcome you were aiming for, and drafts the point-by-point response. ``` you → "review the discussion section of my thesis chapter" claude → reads the .tex, extracts that section, runs the audits, reports what to fix in order of impact ``` --- ## The six skills | Skill | Use it for | Course units | |---|---|---| | **sciwrite-prose** | Sentence and paragraph editing: clutter, active voice, verbs, nominalisations, punctuation, parallelism, keyword consistency, acronyms | 1–3 | | **sciwrite-manuscript** | IMRaD structure: tables and figures, Results, Methods, Introduction, Discussion, Abstract; verb tense per section | 5 | | **sciwrite-process** | Getting it written: pre-writing, the 70/10/20 split, drafting without perfectionism, revision, pre-submission checklist | 4 | | **sciwrite-publish** | Journal choice, submission, responding to reviewers, doing a peer review, authorship, plagiarism, predatory journals | 6 | | **sciwrite-proposals** | Review articles, grant specific aims and research plans, recommendation letters, personal statements | 7 | | **sciwrite-outreach** | Lay summaries, press interviews, risk communication, science news stories, social media | 8 | Each skill keeps its `SKILL.md` short and loads detailed reference files only when the task needs them, so asking for a one-paragraph cleanup does not drag eight units of doctrine into context. --- ## The scripts Four Python scripts (standard library only, no dependencies) do the mechanical detection so the model spends its attention on judgment: | Script | What it finds | |---|---| | `extract_text.py` | Plain text and a section map from `.tex`, `.docx`, `.md`, `.txt` — so "review my Discussion" works on a real LaTeX manuscript without pasting anything | | `prose_audit.py` | Dead-weight phrases, blobs, long-for-short, redundancy, passive voice, `to be` density, nominalisations, buried predicates, double negatives, `there is/are`, adverbs, undefined acronyms, transition-word pile-ups, paragraph length | | `keyword_consistency.py` | Terminology drift between sections (Methods says *obese group*, Results says *heavier group*), and acronyms defined in one section but reused in another | | `numeric_consistency.py` | Sample sizes that disagree across sections, abstract numbers absent from the body, excessive significant figures, mismatched precision in `mean ± SD` | Everything supports `--json`. They report **candidates, not verdicts** — passive voice is legitimate in Methods, a repeated keyword is mandatory, and `PSNR` may be standard in your venue. ```bash python scripts/prose_audit.py paper.tex --section discussion python scripts/keyword_consistency.py paper.tex --terms "obese group,control arm" python scripts/numeric_consistency.py paper.tex --json ``` --- ## Install ### Any agent (Claude Code, Cursor, Codex, Copilot, Gemini CLI and others) ```bash npx skills add dvdsosa/scientific-writing-skills ``` The [skills CLI](https://skills.sh) asks which agents and which skills to install; add `-g` to install for your user rather than for the current project, or `--skill sciwrite-prose` to pick one skill. ### Claude Code plugin ```bash claude plugin marketplace add dvdsosa/scientific-writing-skills claude plugin install sciwrite ``` Or from a local clone: ```bash git clone https://github.com/dvdsosa/scientific-writing-skills.git claude plugin install ./scientific-writing-skills ``` ### Running the scripts The scripts live inside the `sciwrite-prose` skill (`skills/sciwrite-prose/scripts/`, also reachable as `scripts/` at the repository root). The skills find them wherever `sciwrite-prose` was installed — plugin, `npx skills add` for a project or globally, or a manual copy into `~/.claude/skills/`. Install `sciwrite-prose` alongside any other skill you choose; without it, `sciwrite-manuscript` and `sciwrite-process` fall back to doing the checks by reading. To call the scripts yourself, point at the clone: ```bash python ~/path/to/scientific-writing-skills/scripts/prose_audit.py paper.tex ``` Pass the **master** `.tex` file, not a single chapte ````