# Writing research instructions for AutoScholar (the per-paper `CLAUDE.md`)

A 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).

## What the file is — and is not

- 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.
- 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.
- Plain Markdown; optional YAML frontmatter with `mode`, `discipline`, `title` (used to prefill the launch form only).

## Required content (12 sections)

1. **Objective and scope** — one precise question; what is in/out; non-goals.
2. **Domain and mode** — discipline; primary mode (`empirical`, `computational`, `theoretical`, `review`, `experimental`, `humanities`); secondary modes; methodology and why it fits.
3. **Contribution and novelty** — expected contribution; closest prior work; novelty in qualified terms.
4. **Literature/source rules** — indexes to search, minimum verified sources, must-read identifiers, claim-to-source mapping.
5. **Evidence rules** — data sources (exact series/tables/licenses), simulations (labelled synthetic), formal objects, corpora.
6. **Procedure** — pre-registered steps; what is confirmatory vs exploratory.
7. **Baselines, robustness, falsification** — what would overturn the claim; which checks are mandatory.
8. **Reproducibility and artifacts** — `code/reproduce.sh`, pinned environment, seeds, logs, registered numbers.
9. **Manuscript structure and LaTeX standards** — sections, length target (depth over length), figure/table conventions.
10. **Review, revision, quality** — what the independent reviewer should attack.
11. **Limitations, ethics, legal** — constraints the paper must state and respect.
12. **Acceptance criteria** — concrete, checkable conditions for success.

Missing sections are reported as warnings at upload; the run can still start, but vague briefs produce weak papers.

## Choosing the mode

| Mode          | Use when                           | Mandatory evidence (publication gates)                                                                 |
| ------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------ |
| empirical     | real data analysis                 | data manifest with licenses/hashes, executed code with logs, robustness, every reported number traced  |
| computational | algorithms/AI/systems              | executable benchmark, baselines, seeds, ablations, logs                                                |
| theoretical   | proofs/models                      | formal statements, complete derivations/proofs, counterexample search                                  |
| review        | literature synthesis               | search strings/dates/counts, screening records, ≥ 10 verified sources                                  |
| experimental  | simulations/authorized experiments | protocol, observed-vs-synthetic labelling, uncertainty; **human approval required before publication** |
| humanities    | textual/interpretive               | primary-source provenance, quoted evidence with locators                                               |

Medicine, biology, law and psychology always require human approval before publication regardless of mode.

## Good practice

- Give exact identifiers (DOIs, arXiv ids, dataset DOIs, API series ids). The literature tool verifies every citation; unverifiable references are never cited.
- 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.
- Say explicitly whether synthetic data is allowed. If the only data is simulated, say so and expect the paper to be labelled accordingly.
- State the null-result pathway. Null results are publishable; fabricated positives are not.
- Avoid prescribing agent names, tools or platform internals: describe the science.

## Starter templates

`research/templates/{general,empirical,theoretical,computational,review}/CLAUDE.md` — visible in the admin under _Templates_ ("Use this template" prefills _New Research_).