scientific-writing

Scientific Writing

Conventions for structuring research papers and for the drafting workflow. This skill owns the paper's structure and process; it delegates:

• citation finding/verification and the search-protocol appendix to backing-claims,
• LaTeX mechanics (semantic environments, restatable theorems, dual article/slides builds, noweb appendices) to latex-writing,
• reading and uploading annotated drafts to remarkable.

Questions, hypotheses, contributions: full traceability

The skeleton of the paper is the mapping between contributions, research questions and hypotheses. Enforce all of these:

1. Two kinds of research questions, separately numbered. Substantive questions ask about the world; methodological questions ask whether the study's own instruments work (do independent classifications agree? does coding from logs match coding from think-aloud?). Methodological questions get their own environment and counter, so they never renumber the substantive ones. See references/question-structure.md for the LaTeX pattern.
2. Every contribution is held to account by a research question. The introduction has a Contributions subsection; each listed contribution names the question that tests it. A methodological contribution (an instrument, a coding scheme, a triangulation) gets a methodological question. If a contribution has no question, either add the question or drop the claim.
3. Hypotheses are predicted answers. Each hypothesis answers exactly one question; descriptive/exploratory questions have no hypothesis and say so. If an overarching claim is not directly falsified but supported by inference to the best explanation, state that explicitly in the method overview.
4. State once, restate twice. Each question and hypothesis is stated once (introduction/theory) in a restatable environment, restated in the method overview together with how it will be answered, and restated in the conclusions together with its answer so far. Reference by \cref, never literal "RQ1"/"H2".

Method section

• Overview before details: open by restating every question and hypothesis with its mode of answer (which data, which test, which section), then give the details in subsections.
• Data collection in chronological order of the study, and motivate each instrument at the point in time it is used: if an instrument is administered at start and end, the start section motivates only the start administration and a separate end-of-course section motivates the re-administration.
• Do not duplicate a companion study's instrument. When a companion paper collects data in the same setting (same course, same cohort), use its measurements instead of writing a parallel instrument, and let this study's own instruments test only what the companion's do not cover. State the division of labour in the method (which scores come from where), keep the instruments' platform titles distinguishable for participants and analysis alike, and discuss alternatives (e.g. established inventories) against the combined design.
• Validated instruments stay verbatim. Do not reword items of a validated questionnaire, even where wording fits the setting poorly; note the tension in prose instead. Search for and cite published criticisms of the instrument, and derive robustness checks from them (e.g. scoring a subscale separately).
• Guard against circularity: a classification must never be derived from the same data it is later correlated with; say explicitly which sources each classification uses.

Literate-program appendices

Every questionnaire/quiz/survey the study administers, and every quantitative analysis it runs, is a literate program in the paper's appendix: one noweb source that weaves into the appendix chapter and tangles into the runnable artifacts (e.g. the platform's quiz JSON, the analysis script).

• The prose documents the data-file schemas; this doubles as the study's code book.
• Instrument definitions and their analysis share constants (e.g. item titles as result-file column keys) so they cannot drift apart — ideally in the same source file, side by side.
• Uniform instruments are generated, not hand-written. When the items share one form (a validated questionnaire: twenty items, the same five responses), do not tangle the platform's JSON directly: state the instrument once — titles, items, response anchors, instructions — in a constants chunk, tangle a small generator that unfolds it into the platform files, and have the analysis program include the same constants chunk (titles find the reports, anchor texts map answers back to scores). Reference: vt-debug's rspq.nw (make_rspq.py + analyze_rspq.py).
• Cross-reference both ways: the method section points to the appendix program, the appendix points back to the sections that motivate each piece.
• End-to-end automation, both directions. The programs reach into the platform themselves: they create the instruments (e.g. canvaslms quizzes create) and they fetch the results back (e.g. the student-analysis report via the platform CLI's own importable machinery) — course names and instrument titles are known constants, so nothing is clicked or downloaded by hand. Where a fetch cannot be automated yet, mark it XXX with a tracking issue rather than settling for a manual step silently.
• LLM-assisted coding, human-verified. For open-text answers that need qualitative coding, the analysis program pre-codes them with an LLM (the llm package; prompt states the coding scheme, answers in JSON) and writes the suggestions into columns separate from the human coder's verified codes — the sheet always shows which is which, and the human's codes are the data.
• Build mechanics (article-only noweb.sty, Makefile rules, tangle recipes, the syntax-highlighted weave): latex-writing's references/dual-beamer-article.md section "Literate-program appendices", and the literate-programming skill for the standard tominted recipe.
• Validate tangled artifacts in the round that creates them (JSON parses, Python compiles, quiz validators pass) — and test instrument creation end to end against a sandbox course before the real one.

Review rounds

A draft iterates in review rounds; each round is one atomic unit and lives on its own branch with its own PR. Name both after the draft version the round produces — branch review-round-vN, PR to the default branch titled "Review round: draft vN (YYYY-MM-DD)" — so branch, PR, commit message and reMarkable name all carry one identifier (the round that processes v48's comments and uploads v49 is review-round-v49; round counts and draft versions diverge, so never number by round):

1. Open the round: branch review-round-vN off the default branch. The round's work happens here; the PR opens when the round's draft is uploaded.
2. Read all annotated pages of the previous draft (remarkable skill: content_type=annotations to list the pages, render_merged images to read the handwriting).
3. Interpret every comment; apply all edits of the round.
4. New literature needs discovered in a round go through backing-claims (find, verify, provenance block) and into the search-protocol appendix in the same commit.
5. Rebuild all outputs; verify: zero errors, no unresolved references, restatement counts unchanged where expected.
6. One commit per round, without asking; the commit message lists the round's changes and names the draft version it produces ("This commit is the version uploaded to reMarkable as draft YYYY-MM-DD, vN"), so every uploaded draft maps to exactly one commit. Commit at upload time — never upload a draft whose source is uncommitted. Push after committing — the paper repo and, when skills changed, the skills repo (mind that the first push of a fresh repo needs git push -u origin <branch>; a GitHub repo that only ever received issues counts as fresh).
7. Upload the new draft as "<Title> (draft YYYY-MM-DD, vN)" with N incremented.
8. Open the PR (gh pr create), listing the round's changes; use closes #N for issues the round resolved, so merging closes them. Merging the PR ends the round; the next round starts at step 0 with a new branch and PR.

Cite the principle wherever the argument is made

When a passage argues from a theoretical principle the paper rests on — the design rationale of an instrument item ("a test of discernment must not point out the aspect"), the wording of a stem, a coding or analysis choice — cite the principle's source in that passage (e.g. \autocite[p.~91]{NCOL}), not only where the principle was first introduced. The citation is the support for the argument: a reader of an appendix paragraph does not carry the introduction's citation with them, and a reviewer sees an unsupported claim. This holds for every instance — each item rationale that invokes the principle, each stem redesign in a review round. "Already cited earlier in the paper" is not a reason to omit it; repeating the same key and page is correct, not redundant. (Verification per backing-claims happens at the first use; later uses of the same verified claim reuse the key and page.)

Open questions and pending decisions

• Mark open decisions with % XXX and deferred work with % TODO in the source, stating the alternatives and what resolves them; resolve or carry them forward consciously each round — never silently drop one.
• Mirror them as GitHub issues whenever the paper repository has a GitHub remote (git remote -v). This is standing authorisation: create the issues with gh issue create without asking. Conventions:
  • One issue per XXX/TODO item; the title states the decision or task, the body gives the file and section, the context, the alternatives, and what resolves it.
  • Annotate the source comment with the issue number — % TODO(#12): ... — so source and tracker stay linked.
  • Per round: new XXX/TODO items get new issues; items resolved in the round get their issues closed (gh issue close N --comment ...) in the same round, referencing the commit.
  • An item tracked elsewhere too (e.g. a nytid todo for work the author must do personally) still gets the issue; note the cross-link in both.
• Anonymise course/institution details before submission (keep a % TODO at the top of the method section until done).

Checklist (per round)

• Every contribution names its research question
• Methodological questions separate from substantive ones
• Each question restated in method overview (with mode of answer) and in conclusions (with answer)
• Instruments motivated at their chronological place
• Questionnaires and analyses exist as literate appendix programs; tangled artifacts validated
• New citations verified and searches documented (backing-claims)
• Every argument from a theoretical principle cites its source where the argument is made, not only at first mention
• XXX/TODO items mirrored as GitHub issues (new ones opened, resolved ones closed) when the repo is on GitHub
• Both outputs build clean; committed as one round; new draft uploaded