Research Code Documentation Template
Three documents and two sheets that trace every exhibit to its script, then flag one edited after its output was last written.
Free download · No account needed
Output Map
Table 2, Ashgrove Wage Compliance Study
| Script | Script modified | Output file | Output modified | Status |
|---|---|---|---|---|
| 03_reg_compliance.R | 19 Nov, 15:47 | table2.csv | 24 Oct, 14:33 | Stale |
The script gained a referee-requested control on 19 November. Its output file has carried the 24 October timestamp since, twenty-six days earlier, so the number in the draft is what the script produced before the control existed.
Every reproducibility guide gives the same fix: rewrite the pipeline into a dependency tool like Make or Snakemake, or start from a Cookiecutter skeleton. Both organize a project. Neither checks whether a record already written is still true. The AEA's data and code policy requires a submitting README to map every program to its output and exhibit. The Social Science Data Editors' template it endorses turns that requirement into a table, naming the program and line behind each one. This pack builds that table, then checks it against two timestamps every file already carries.
The pack ships filled in for the Ashgrove Wage Compliance panel. Five scripts turn a raw payroll extract into a summary table, two regressions and an event-study figure across 9,920 establishment-quarter observations. A referee asked for an establishment-size control on the compliance regression. The script was edited 19 November and never re-run, so its output file carries a 24 October timestamp, twenty-six days earlier. Output Map catches the gap from those two dates alone. A sixth script, checking a threshold the paper never reports, produces a file no exhibit claims and the master never calls.
Open the pack in River and the agent reads your scripts folder and draft manuscript. It builds the File Register from what it finds, then checks every claimed exhibit against its script's and output's real modified times. Or download the documents and sheets and fill them in by hand. The panel this pack verifies usually starts at the dataset cleaning and codebook pack. The same numbers feed the methods section and get reformatted by the results table and figure pack for a target journal. More research packs sit alongside this one.
What's in the pack
Output Map sheet
Every exhibit's script, both files' real modified times, and a status computed by comparing them: current, stale or orphaned, never typed in by hand.
File Register sheet
Every script's purpose, what it reads and writes, and whether the master script actually calls it, inventoried before anything gets checked against it.
README
The pipeline's run order and contents, copied from the master script's own source lines. The panel it describes is what the results section writer later turns into prose.
Environment Note
The exact software and package versions used, any random seed and where it is set, and a runtime estimate, so a replicator knows what to install.
Data Provenance Statement
Where every data source came from, what access it requires, and how a future researcher could obtain it again, including a source behind a fee or an agreement.
A script's own timestamp, never a memory of it
The standing space rule every prompt reads first. A journal's own README template leaves the exhibit-to-script table to be filled in by hand. This rule is what gets it checked instead.
How to use it
- 1
Open in River, or download it
Open the pack in River and the agent reads your scripts folder and draft manuscript with you. Or download the blank documents and CSV sheets instantly, filled in with the worked example.
- 2
Send the folder and the paper
Every script in the folder, not just the ones you remember, plus the draft naming its tables and figures by number. A folder listing beats a description of the main scripts.
- 3
Build the register, then the map
File Register inventories every script's purpose and dependencies first. Output Map then traces each exhibit in the paper to the exact script and line that produces it.
- 4
Check both files' real timestamps
The script's own modified time against its output's. A script edited after its output was last written is flagged stale, and a file or script nothing claims is flagged orphaned.
Frequently asked questions
Is this template free?
Yes. Download the pack's three documents and two sheets with no signup and no credit card, filled in for the worked example. Edit with AI installs the same pack as a private River workspace. There, the agent reads your own scripts folder and draft manuscript, and builds the register and the map from your files.
What format are the downloaded files?
Word documents for the README, Environment Note and Data Provenance Statement, and CSV for File Register and Output Map, all in one zip. Nothing needs converting: they open in Word, Pages, Google Docs, Excel, Numbers and Sheets. Inside River the same content opens as live Docs and Sheets that update as you send more files.
Doesn't a build tool like Make or Snakemake already solve this?
A build tool re-runs a pipeline it already understands as a formal dependency graph. That is a real fix, once every script has been rewritten into that tool's own rule syntax. This pack does not require that rewrite. It reads the modified time already sitting on every script and output file in an ordinary folder, so it works on the pipeline you already have.
What counts as an orphaned script versus a stale exhibit?
Stale means the script producing a claimed exhibit was edited after its output file was last written. The number on the page may not match what the code would produce today. Orphaned means a script or output file exists that neither the paper's own exhibit list nor the master script's run order accounts for, in either direction.
I don't have a master script that runs everything in order. Does the pack still work?
Yes, with one honest gap. File Register records the run order you can describe rather than inventing one, and Output Map still traces each exhibit to its script. What it cannot check without a master script is whether a script nobody calls was meant to run at all, and the register says so rather than guessing.
Does this check whether my analysis or specification is any good?
No. It checks whether the record of what produced what still matches the files you have, not whether the specification behind any exhibit is defensible. Testing that specification against reasonable alternatives is a separate question a dedicated robustness checks pack answers. Re-running a reviewer's requested control is what would make Output Map current again.
Find out which exhibit is actually stale
Send your scripts folder and your draft. The register and the map come back with every exhibit checked against the files' own timestamps.
Edit with AI