spb/autoscholar

1# Writing research instructions for AutoScholar (the per-paper `CLAUDE.md`)23A research instruction file is the complete brief for one autonomous research run. It is a product input written for a researcher, not a configuration file: it says _what_ to study, _how_ to study it, _what evidence counts_, and _when the result is acceptable_. The platform supplies everything else (sandbox, tools, artifact contract, quality gates, LaTeX class, publication).45## What the file is — and is not67- It is loaded verbatim as the project instructions of an isolated Claude Agent SDK workspace on a MacLustr worker. It is frozen and hashed when uploaded; every run references one immutable version.8- It cannot grant permissions, reach credentials, change tools or alter platform rules. Text that targets the platform (sudo, SSH, API keys, "ignore the platform policy", system paths) is rejected at upload.9- Plain Markdown; optional YAML frontmatter with `mode`, `discipline`, `title` (used to prefill the launch form only).1011## Required content (12 sections)12131. **Objective and scope** — one precise question; what is in/out; non-goals.142. **Domain and mode** — discipline; primary mode (`empirical`, `computational`, `theoretical`, `review`, `experimental`, `humanities`); secondary modes; methodology and why it fits.153. **Contribution and novelty** — expected contribution; closest prior work; novelty in qualified terms.164. **Literature/source rules** — indexes to search, minimum verified sources, must-read identifiers, claim-to-source mapping.175. **Evidence rules** — data sources (exact series/tables/licenses), simulations (labelled synthetic), formal objects, corpora.186. **Procedure** — pre-registered steps; what is confirmatory vs exploratory.197. **Baselines, robustness, falsification** — what would overturn the claim; which checks are mandatory.208. **Reproducibility and artifacts** — `code/reproduce.sh`, pinned environment, seeds, logs, registered numbers.219. **Manuscript structure and LaTeX standards** — sections, length target (depth over length), figure/table conventions.2210. **Review, revision, quality** — what the independent reviewer should attack.2311. **Limitations, ethics, legal** — constraints the paper must state and respect.2412. **Acceptance criteria** — concrete, checkable conditions for success.2526Missing sections are reported as warnings at upload; the run can still start, but vague briefs produce weak papers.2728## Choosing the mode2930| Mode          | Use when                           | Mandatory evidence (publication gates)                                                                 |31| ------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------ |32| empirical     | real data analysis                 | data manifest with licenses/hashes, executed code with logs, robustness, every reported number traced  |33| computational | algorithms/AI/systems              | executable benchmark, baselines, seeds, ablations, logs                                                |34| theoretical   | proofs/models                      | formal statements, complete derivations/proofs, counterexample search                                  |35| review        | literature synthesis               | search strings/dates/counts, screening records, ≥ 10 verified sources                                  |36| experimental  | simulations/authorized experiments | protocol, observed-vs-synthetic labelling, uncertainty; **human approval required before publication** |37| humanities    | textual/interpretive               | primary-source provenance, quoted evidence with locators                                               |3839Medicine, biology, law and psychology always require human approval before publication regardless of mode.4041## Good practice4243- Give exact identifiers (DOIs, arXiv ids, dataset DOIs, API series ids). The literature tool verifies every citation; unverifiable references are never cited.44- Size the study to the budget (default USD 25, 240 minutes) and to a CPU-only node. A small correct study beats an ambitious incomplete one.45- Say explicitly whether synthetic data is allowed. If the only data is simulated, say so and expect the paper to be labelled accordingly.46- State the null-result pathway. Null results are publishable; fabricated positives are not.47- Avoid prescribing agent names, tools or platform internals: describe the science.4849## Starter templates5051`research/templates/{general,empirical,theoretical,computational,review}/CLAUDE.md` — visible in the admin under _Templates_ ("Use this template" prefills _New Research_).52