# Research Repo Doctor

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/Tom409114/research-repo-doctor  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/research-repo-doctor

## Description
Deterministic Artifact Evaluation preflight and run-path grader for research repositories.

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "research-repo-doctor": {
    "command": "npx",
    "args": ["-y","research-repo-doctor"]
  }
}
```

## Documentation & README

# Research Repo Doctor

<!-- mcp-name: io.github.Tom409114/rrdoctor -->

Get your research artifact ready for Artifact Evaluation before the deadline:
scan the repo, scaffold the easy fixes, verify the run path, and generate the appendix.

Web demo for public repos: <https://research-repo-doctor-bckncrcwwmg6jrbsrd6btj.streamlit.app/>
If the hosted demo is waking up or reinstalling dependencies, the local zero-install
command below is the reliable fallback:

```bash
uvx rrdoctor scan .
```

Maintainers can check anonymous demo access with
`python scripts/check_live_demo.py https://research-repo-doctor-bckncrcwwmg6jrbsrd6btj.streamlit.app/`.

![rrdoctor demo](docs/demo.gif)

[![CI](https://github.com/Tom409114/research-repo-doctor/actions/workflows/ci.yml/badge.svg)](https://github.com/Tom409114/research-repo-doctor/actions/workflows/ci.yml)
[![rrdoctor readiness](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Tom409114/research-repo-doctor/main/.rrdoctor-badge.json)](https://github.com/Tom409114/research-repo-doctor)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)

`rrdoctor` is a local CLI and GitHub Action for research artifact preparation. It audits
whether a repo is reviewable, citable, and close to runnable; scaffolds safe mechanical
fixes; maps findings to an AE-style readiness level; and turns the rest into a checklist
any coding agent or human can finish.

## Make it a pull-request gate

The GitHub Action is the main adoption path: run the CLI while preparing the
artifact, then keep the same deterministic preflight on every pull request.

```yaml
name: Reproducibility preflight

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  rrdoctor:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: Tom409114/research-repo-doctor@v0.2.24
        with:
          profile: standard
          fail-on: error
```

The full [GitHub Action guide](docs/github-action.md) covers sticky PR comments,
new-finding baselines, agent plans, appendices, and complete AE prep packets.

## AE deadline loop

```bash
uvx rrdoctor prepare . --profile acm --out-dir rrdoctor-prep

# Or run the pieces explicitly:
uvx rrdoctor scan . --profile acm
uvx rrdoctor fix . --write
uvx rrdoctor appendix . --profile acm --output ARTIFACT_APPENDIX.md
uvx rrdoctor verify . --profile acm
uvx rrdoctor verify . --profile acm --run --timeout 600 --fail-on error  # trusted repos only
# Or pin the official quickstart command as the dynamic gate:
uvx rrdoctor verify . --profile acm --command "python train.py config/default.py" --run --timeout 600 --fail-on error
```

For trusted repositories, `rrdoctor verify --run` can go beyond static checks. For supported
Python repositories it creates a temporary isolated environment, installs declared
dependencies, and executes the declared entrypoint there under a timeout. Other ecosystems
retain an explicit resolver preflight. With the default gate (`--fail-on error`), failed or
blocked dynamic L2/L3 steps return a nonzero exit code. Use `--command` when the artifact has
a specific smoke-test or quickstart command that reviewers should run. Dynamic mode may run
dependency build/install hooks as well as the entrypoint, so never use it on untrusted code.
`rrdoctor prepare` writes the report, agent plan, artifact appendix, and verification ladder
into one local evidence directory.

Artifact Evaluation chairs and lab maintainers can use the
[AE chair guide](docs/ae-chair-guide.md) for optional pre-submission wording and
CI examples.

For public calibration evidence, see the
[80-repository data brief](docs/corpus-data-brief.md) and the
[nanoGPT first-run regression case study](docs/case-studies/nanogpt.md).

## What it catches

- **"Your `--seed` flag does nothing."** `RRD052` spots code that declares a seed option but
  never calls `random.seed`, `np.random.seed`, `torch.manual_seed`, `tf.random.set_seed`, or
  `random_state=seed`.
- **"This worked on my laptop."** Local-only data paths, missing data provenance, and
  undocumented retrieval steps.
- **"The environment silently changed."** Unpinned dependencies, missing runtime versions,
  undeclared imports, and absent dependency manifests.
- **"The notebook lies."** Stale outputs, out-of-order execution, checkpoint artifacts, and
  secret-like notebook output.
- **"Reviewers cannot tell how to cite or rerun this."** Missing license, citation, CI,
  tests, changelog, results provenance, or experiment entrypoint.

## Install

Run once, without installing:

```bash
uvx rrdoctor scan .
```

Alternatives:

```bash
pipx run rrdoctor scan .
pip install rrdoctor
rrdoctor scan .
```

Developer install from source:

```bash
git clone https://github.com/Tom409114/research-repo-doctor.git
cd research-repo-doctor
python -m pip install -e ".[dev]"
rrdoctor scan .
```

## Fix the easy gaps

Let `rrdoctor` create the safe scaffolding for you. It is deterministic, idempotent, and
never overwrites existing files.

```bash
rrdoctor fix . --write
```

It can scaffold missing governance docs, citation metadata, data/results provenance notes,
a reproducible-seed helper, changelog entries, and common research `.gitignore` entries.
The hard parts become a reviewable plan:

```bash
rrdoctor plan . --output plan.md
```

## Use with your coding agent

Paste this into Claude Code, Cursor, GitHub Copilot, or any other coding agent:

```text
Use rrdoctor as the deterministic, offline, no-API-key grader for this research repo.

Run:
rrdoctor scan . --format json --output baseline.json
rrdoctor plan . --output plan.md

Work through plan.md without weakening rrdoctor checks.

Definition of done:
rrdoctor scan . --baseline baseline.json --fail-on-new error
```

The final command is the objective gate: it verifies the agent's work against the starting
baseline and fails only on newly introduced errors.

Copyable agent templates are available for Agent Skills / Claude Code-style workflows and
Cursor project rules under [integrations/](integrations/).

Keywords: research software, reproducibility, artifact evaluation, repository audit, auto-fix,
coding agents, AGENTS.md, GitHub Action, notebooks, data availability, citation metadata.

## Help calibrate the rules

The fastest way to improve rrdoctor is real scan feedback from real research
repositories. After one scan, the low-friction
[10-minute trial report](https://github.com/Tom409114/research-repo-doctor/issues/new?template=trial_report.yml)
asks only what was useful, wrong or missing, and whether the tool fits a real
deadline. For a focused rule report, please open a
[false-positive](https://github.com/Tom409114/research-repo-doctor/issues/new?template=false_positive.yml),
[false-negative](https://github.com/Tom409114/research-repo-doctor/issues/new?template=false_negative.yml),
[scan-case](https://github.com/Tom409114/research-repo-doctor/issues/new?template=scan_case.yml),
or [new-rule](https://github.com/Tom409114/research-repo-doctor/issues/new?template=rule_request.yml)
issue. Include the rule ID, command, rrdoctor version, and a sanitized minimal
repo shape. See [feedback and calibration](docs/feedback.md) for the short checklist.

## Why this matters

Research code often lands on GitHub under deadline pressure. A reviewer or future lab
member finds a promising repository and then loses hours because the environment is
underspecified, data paths are local, notebooks contain stale outputs, dependencies are
unpinned, or the citation is unclear.

Research Repo Doctor turns those recurring release blockers into deterministic checks with
concrete remediation - and, where it is safe to do so, scaffolds the mechanical starting
points. It is built to sit in the ordinary maintenance path: run locally while preparing
a release, then run automatically on pull requests through GitHub Actions.

The audit runs without an AI API key, network access, or hosted service. That same
determinism makes it an honest grader: it can verify fixes made by a person or a coding
agent.

```text
audit -> fix -> plan -> (your coding agent / you) -> verify -> PR
  |       |       |                                  |
  |       |       rrdoctor plan                      rrdoctor scan --baseline
  |       rrdoctor fix --write                       --fail-on-new error
  rrdoctor scan
```

## What's new in 0.2.24

- **Better systems-artifact coverage**: existing checks now recognize Cargo,
  CMake, Meson, container, and Nix evidence plus documented artifact scripts
  and Cargo commands across entrypoint, test, CI, and release workflows.
- **Quieter static scans**: target-source `SyntaxWarning` noise is suppressed,
  and escaped Python exception text no longer looks like a local Windows path.
- **A rechecked first-run trust case**: public PyPI `rrdoctor==0.2.23` still
  scores nanoGPT as `Functional` at 76/100 with 0 errors, while the original
  noisy `RRD050` and `RRD063` findings remain absent.
- **An explicit JOSS boundary**: the draft-paper notes now separate the
  more-than-six-month public-history gate from research-use, authorship,
  conflict-of-interest, and AI-disclosure evidence that maintainers must supply.
- **A configuration file that actually governs the scan**: CLI and MCP calls
  load the target repository's `.rrdoctor.yml` from any working directory;
  profile, report, threshold, failure, include/exclude, and rule settings now
  work beneath explicit CLI overrides.

## What's new in 0.2.23

- **A safer release path**: the hosted demo can stay pinned to the latest
  published PyPI package while a new release propagates, avoiding broken
  Streamlit deployments during Trusted Publishing.
- **A first-class GitHub Action path**: a compact pull-request workflow now
  appears near the top of the README and is guarded by public-readiness tests.
- **A shorter feedback loop**: completed web-demo scans link to a structured
  10-minute trial report for useful findings, false positives, false negatives,
  and real deadline fit.
- **Official MCP Registry distribution**: `v0.2.24` is published as
  [`io.github.Tom409114/rrdoctor`](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.Tom409114/rrdoctor),
  with MCP support remaining an optional extra rather than a core scanner
  dependency. Registry inclusion is distribution metadata, not endorsement or
  evidence of adoption.
- **Stronger dynamic verification coverage**: an offline integration test proves
  L3 can install and import a declared local wheel inside its temporary Python
  environment.

## What's new in 0.2.22

- **Real Python environment verification**: `rrdoctor verify --run` now creates
  a temporary isolated venv, installs the repository's declared dependencies,
  and runs L3 with that interpreter and PATH instead of stopping at a resolver
  dry run.
- **Honest execution boundaries**: verification reports disclose dependency
  build-hook risk, redact machine-specific temporary paths, and remove the
  temporary environment after the run. Other ecosystems retain an explicit
  resolver preflight.
- **Stronger isolation checks**: inherited `PYTHONHOME` and `PYTHONPATH` values
  are removed, and versioned launchers such as `python3.10` are redirected to
  the temporary environment.

## What's new in 0.2.21

- **More honest corpus evidence**: the public 80-repository calibration corpus
  now has 80 focused review notes, 0 repositories awaiting focused review, and
  a concise data brief that explains what the corpus does and does not prove.
- **Lower-noise model-release scans**: `RRD050` and `verify` now recognize
  common model-release entrypoints such as `demo.py`, `inference.py`,
  `predict.py`, `sample.py`, and `generate.py` in root, `scripts/`, and
  `tools/` layouts.
- **Less noisy secret checks**: `RRD063` and `RRD090` now require stronger
  entropy evidence for generic `api_key`/`token`/`secret`/`password`
  assignments while still flagging provider-shaped keys.
- **More agent integrations**: the repository includes copyable GitHub Copilot
  instructions alongside the existing Agent Skill and Cursor templates for the
  baseline -> plan -> verify loop.
- **Clearer launch artifacts**: the JOSS draft now states the evaluation
  evidence and limitations more explicitly, and the live-demo check now follows
  Streamlit's anonymous redirect handshake before deciding whether the app is reachable.

## What's new in 0.2.20

- **Lower-noise mature scientific package scans**: `RRD010` now recognizes
  common license filenames such as `LICENSE.txt`, and `RRD043` ignores
  CI/devcontainer paths, tests/fixtures, URL path segments, and documented
  placeholder/example absolute paths.
- **Lower-noise library and secret heuristics**: `RRD050` no longer treats
  mature package/library projects, including common nested `package/` layouts,
  as missing paper experiment entrypoints, and `RRD090` ignores URL query
  tokens, local function-call or method-call token variables, generic fake
  tokens in test helpers, and provider-looking substrings embedded inside
  longer biological/test sequences.
- **More reviewed corpus evidence**: SciPy is a focused review case and an
  expected-absent regression gate for `RRD010` and `RRD043`; scikit-image,
  JAX, NetworkX, Keras, Transformers, PyTorch Lightning, Biopython,
  torchvision, MDAnalysis, QuTiP, ESM, stable-diffusion, detectron2,
  DINO, StyleGAN2-ADA PyTorch, instant-ngp, Big Vision, latent-diffusion,
  taming-transformers, generative-models, pytorch-image-models, Brax, ArviZ,
  PyMC, Pyro, TensorFlow Probability, statsmodels, Optax, and the remaining
  corpus entries now add first-run trust gates or focused review evidence. The
  latest 80-repository corpus gate has 0 expected-absent regressions, 80
  reviewed notes, and 0 repositories still awaiting focused review.
- **Less template-like auto-fix output**: `rrdoctor fix --write` can now read
  simple literal `setup.py` metadata statically, without executing repository
  code, when generating citation and provenance scaffolds.
- **More filled Artifact Appendix access notes**: `rrdoctor appendix` reuses the
  same local metadata inference to pre-fill repository URLs and versions for
  legacy `setup.py`/`setup.cfg` projects.
- **More realistic L2 environment checks**: `rrdoctor verify --run` now resolves
  common nested Python requirement files such as `requirements/base.txt` and
  `requirements/main.txt`, plus `.yaml` Conda environment files, instead of
  skipping those repository layouts.
- **Lower-noise notebook secret checks**: `RRD063` now shares the test/fixture
  generic fake-token suppression used by `RRD090`, while still flagging
  standalone provider-style keys.

## What's new in 0.2.19

- **Lower-noise experiment entrypoint detection**: `RRD050` now recognizes
  package-level research binaries such as `t5x/train.py`, documented
  `python3 ${T5X_DIR}/t5x/train.py` commands, and notebook-first artifacts with
  clearly named demo/example/reproduce notebooks such as `graphcast_demo.ipynb`.
- **More first-run corpus evidence**: focused review notes now cover 32/60 seed
  corpus repositories. The latest 60-repository static corpus scan has 0
  expected-absent regressions and keeps t5x and GraphCast as entrypoint
  regression gates.

## What's new in 0.2.18

- **Lower-noise dependency checks**: `RRD034` now parses Python AST imports
  instead of regex-matching source text, so comments, docstrings, and prose
  examples do not look like missing packages.
- **Runtime-focused dependency signal**: docs, tests, benchmarks, vendored code,
  maintainer tooling, `conftest.py`, build-system requirements, and local
  sibling modules are filtered out before dependency-gap reporting.
- **More corpus review evidence**: focused review notes now cover 30/60 seed
  corpus repositories, including scikit-learn, Astropy, scvi-tools, and DINOv2
  checks for dependency-signal noise.
- **Current install path**: PyPI, GitHub Action examples, demo requirements,
  citation metadata, and the self-scan report are aligned to this release.

## What's new in 0.2.15

- **Clearer verification evidence**: `rrdoctor verify` reports now lead with
  the gate outcome, failure threshold, timeout, trust boundary, rerun command,
  and the source of any L3 dynamic command.
- **Stronger Artifact Appendix scaffolding**: `rrdoctor appendix` now pre-fills
  local README/project metadata, dependency manifests, data/results docs,
  config files, and detected entrypoint commands where available.
- **More useful generated data notes**: `rrdoctor fix --write` carries over
  candidate dataset URLs, DOIs, README data commands, and local data scripts
  when scaffolding `DATA.md`.
- **Maintainer launch gates**: `python scripts/check.py` and
  `python scripts/check_public_readiness.py` provide cross-platform local checks
  for release, JOSS, Artifact Evaluation, and public outreach readiness.

## What's new in 0.2.14

- **One-command AE evidence packet**: `rrdoctor prepare` writes the static
  report, agent fix plan, Artifact Appendix, and verification ladder into one
  local directory for deadline handoff.
- **CI-uploaded AE packet**: the GitHub Action now supports `prepare: "true"`
  and `prepare-output`, so pull requests and release gates can upload the same
  reviewer-ready packet.
- **Pinned run-path verification**: `verify --command "..."`, the Action
  `verify-command` input, and the MCP `verify` tool let maintainers pin the
  official quickstart command and timeout as the L3 gate.
- **Lower first-run noise**: MAE-style root `main_*.py` scripts, AlphaFold-style
  `random_seed=` plumbing, test-file randomness, and placeholder absolute paths
  are handled more conservatively.

## What's new in 0.2.13

- **Scan reports now lead to the AE workflow**: Markdown reports and agent fix
  plans now include next-step commands for `rrdoctor plan`, `rrdoctor appendix`,
  static `rrdoctor verify`, and trusted-only dynamic `verify --run`.
- **Stronger auto-fix scaffolds**: generated `AGENTS.md` files now include the
  scan -> plan -> baseline verification loop, and generated results-provenance
  notes include local repository context, current result files, and a structured
  result inventory table.
- **Better adoption materials**: public docs now include a feedback/calibration
  path and an Artifact Evaluation chair guide with optional pre-submission
  wording and CI examples.

## What's new in 0.2.12

- **Trusted dynamic Action gate**: GitHub Action users can now set
  `verify-run: "true"` plus `verify-fail-on: error` so trusted dynamic
  verification blocks CI while still uploading the verification report.
- **Agent distribution templates**: repository Copilot instructions, an Agent
  Skill template, and a Cursor project rule make the deterministic
  scan -> plan -> verify loop copyable across coding-agent workflows.
- **Tighter evidence wording**: corpus and JOSS draft wording now distinguishes
  focused review notes from full manual repository audits.

## What's new in 0.2.11

- **First-run trust tuning**: README install/run commands, seeded local RNGs,
  PyTorch parameter initialization, UUID-like identifiers, and classic ML repos
  now produce fewer false positives.
- **Real dynamic gate**: `rrdoctor verify --run --fail-on error` now exits
  nonzero when dependency resolution or the detected run path fails or is blocked.
- **More calibration evidence**: 22 focused review notes are now committed,
  including BERT, CLIP, improved-diffusion, MAE, and AlphaFold follow-ups with
  expected-absent checks for fixed noisy findings.

## What's new in 0.2.10

- **More reliable corpus calibration**: the public evaluation-corpus runner now
  falls back to GitHub archives when `git clone` times out, keeping first-run
  trust checks less dependent on flaky transport.
- **Cleaner maintainer automation**: first-party workflows and documentation
  examples now use current Node 24-compatible GitHub Actions releases.
- **Sharper diagnostics**: `rrdoctor doctor` now reports optional MCP
  integration availability only when the package and import-time dependencies
  actually load.

## What's new in 0.2.9

- **Clearer first-run CLI behavior**: `rrdoctor --version` now reports the
  installed package version, and running bare `rrdoctor` prints the root help
  page successfully.

## What's new in 0.2.8

- **Better README run-path recognition**: README-documented
  `python -m package.train ...` commands now count as experiment entrypoints
  when they map to local repository modules.
- **Stronger dynamic verification for ML launchers**: `rrdoctor verify` now
  recognizes module-runner commands such as
  `python -m torch.distributed.run train.py ...` when they include a local
  Python entrypoint.

## What's new in 0.2.7

- **Better citation scaffolds**: `rrdoctor fix --write` now reads structured
  PEP 621 and Poetry metadata, preserves multiple authors, normalizes SSH git
  remotes, and handles git worktree origin URLs when generating `CITATION.cff`.
- **Lower-noise dependency checks**: `RRD034` now understands PEP 621 environment
  markers and Poetry dependency groups, reducing undeclared-import false positives.

## What's new in 0.2.6

- **Lower-noise secret checks**: Rcpp `Generator token` markers and public
  pkgdown `docsearch.api_key` search configuration no longer trigger `RRD090`,
  while generic credential-like API keys still do.
- **More reliable corpus scans**: the evaluation runner now falls back to
  GitHub archive downloads when `git clone` transport is flaky, without
  installing or executing target repositories.
- **More manual calibration evidence**: the current public corpus snapshot
  covers 60/60 successful static scans, 22 focused review notes loaded in that
  snapshot, and 0 expected-absent regressions.

## What's new in 0.2.5

- **Model-release entrypoints**: README-documented `python scripts/*.py` /
  `python tools/*.py` commands and pyproject-declared CLI commands now count as
  experiment entrypoints, reducing first-run false positives on repositories
  such as Segment Anything and Whisper.
- **ML tools entrypoints**: common `tools/train.py`, `tools/test.py`, and
  related ML framework commands now count for `RRD050`.
- **Seed helper scaffolding**: `rrdoctor fix --write` can scaffold a
  reproducible `set_global_seed(seed)` helper for `RRD052` without overwriting
  project code.
- **Corpus regression gates**: entrypoint fixes are backed by focused review
  notes and `expected_absent` checks in the public evaluation corpus.

## What's new in 0.2.4

- **First-run trust improvements**: root-level `train.py`/`main.py`/`run.py`,
  Snakemake/Nextflow workflows, and README run commands count as experiment entrypoints.
- **Lower-noise security checks**: notebook and repository secret detection now requires
  high-confidence credential-like values before raising blocking errors.
- **More realistic README checks**: concrete training, evaluation, benchmark, workflow, or
  reproduction commands count as evidence for reproducing results.
- **Corpus-backed rule calibration**: the public evaluation corpus tracks false-positive and
  false-negative review notes, expected-absent regression gates, and aggregate rule frequencies.
- **Release hygiene**: citation guidance detection recognizes README Citing sections, BibTeX,
  DOI links, and "please cite" text; local git tags count as deterministic version evidence.
- **Release polish**: the demo GIF is generated, issue access is open, and the committed
  self-scan report is 100/100.

## What's new in 0.2.0

- **`rrdoctor fix`** provides deterministic, idempotent auto-fix for common gaps (governance
  docs, citation metadata, data/results provenance, seed helper scaffolding, changelog, ignore
  entries). Never overwrites.
- **`rrdoctor plan`** emits a tool-agnostic fix plan you can hand to any coding agent; every
  task names the deterministic check that verifies it.
- **Baseline gating**: `rrdoctor scan --baseline report.json --fail-on-new error` fails only
  on newly introduced findings, so large repos can adopt the audit incrementally.
- **`rrdoctor badge`** emits a Shields.io endpoint or SVG artifact-readiness badge.
- **Artifact readiness labels** map findings to an AE-style level: `Available`,
  `Functional`, or `Reproduced-ready`. The numeric score remains as a secondary
  triage signal.
- **First-class PR automation**: the Action posts a sticky PR comment, writes a job summary,
  and can attach the fix plan, using only the built-in `GITHUB_TOKEN`.
- **New rules** include unpinned dependencies, committed notebook checkpoints, pre-commit
  config, and an AGENTS.md task guide for agent and human contributors.

## Quickstart

```bash
rrdoctor scan .                   # deterministic audit (Markdown report)
rrdoctor fix . --write            # apply safe scaffolding for easy gaps
rrdoctor plan . --output plan.md  # tool-agnostic work order for the rest
rrdoctor scan . --format json --output baseline.json --fail-on none
rrdoctor scan . --baseline baseline.json --fail-on-new error  # gate regressions
```

Stricter gate and report file:

```bash
rrdoctor scan . --profile strict --fail-on warning --output rrdoctor-report.md
```

Machine-readable and agent output:

```bash
rrdoctor scan . --format sarif --output rrdoctor.sarif --fail-on none
rrdoctor scan . --format agent --output fix-plan.md
```

Before a submission deadline:

```bash
rrdoctor prepare . --profile acm --out-dir rrdoctor-prep          # one local AE packet
rrdoctor appendix . --profile acm --output ARTIFACT_APPENDIX.md   # appendix + checklist mapping
rrdoctor verify . --profile neurips                               # L1/L2/L3 ladder (static)
rrdoctor verify . --run --timeout 600 --fail-on error              # build + run gate (trusted repos)
rrdoctor verify . --command "python train.py config/default.py" --run --timeout 600
```

Submission profiles: `acm`, `neurips`, `icml`, `ml-paper`, `fair4rs`, `joss` (alongside the
general `minimal`/`standard`/`strict`/`ml` tiers). Static dependency and runtime checks also
understand R, Julia, Rust/Cargo, CMake-based builds, containers, and Nix environments, not just
Python and JavaScript.

## The audit -> fix -> verify loop

A deterministic checker is reproducible and trustworthy but cannot write prose or judge
intent. A coding agent edits well but needs a precise specification and an objective
definition of done. Research Repo Doctor gives you both:

1. **Audit**: `rrdoctor scan` produces deterministic findings.
2. **Fix the easy ones**: `rrdoctor fix --write` scaffolds governance docs, citation metadata,
   provenance notes, a seed helper, a changelog, and ignore entries (idempotent, never
   overwriting).
3. **Plan the rest**: `rrdoctor plan` emits a tool-agnostic work order. Paste it into the
   coding agent of your choice, attach it to an issue, or work it by hand.
4. **Verify**: re-run the audit against a baseline. Because verification is deterministic
   and key-free, it works as an honest grader for changes from any source.

See [docs/agent-workflows.md](docs/agent-workflows.md) and [docs/autofix.md](docs/autofix.md).

## GitHub Action

Add one workflow to many repositories and get consistent reproducibility reports on pull
requests and pushes. The Action requires no API key.

```yaml
name: Reproducibility audit

on:
  pull_request:

permissions:
  contents: read
  pull-requests: write

jobs:
  rrdoctor:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: Tom409114/research-repo-doctor@v0.2.24
        with:
          profile: standard
          fail-on: none
          comment-pr: "true"     # sticky PR comment with the report
          step-summary: "true"   # report in the job summary
          plan: "true"           # attach an agent-ready fix plan
          appendix: "true"       # attach an Artifact Evaluation appendix
          verify: "true"         # attach the L1/L2/L3 verification ladder
          prepare: "true"        # upload a complete AE prep packet directory
          # For trusted repos, add verify-run: "true" and verify-fail-on: error
```

For new-finding gating and a committed baseline, see
[docs/pull-request-automation.md](docs/pull-request-automation.md).

## Example output

```text
Research Repo Doctor Summary
Profile: standard
Readiness: Functional
Score: 64/100
Errors: 0
Warnings: 5
Rules evaluated: 32

How to fix first:
- RRD030 No dependency manifest found: Add pyproject.toml, requirements.txt, or another manifest.
- RRD040 Data availability documentation missing: Add DATA.md, docs/data.md, or a README section.
```

Worked examples live in [examples/reports/](examples/reports/), including a
[fix plan](examples/reports/fix-plan.md) and a [self-scan report](examples/reports/self-scan-report.md).

## Commands

| Command | Purpose |
| --- | --- |
| `rrdoctor scan` | Run the deterministic audit; supports `--baseline` and `--fail-on-new`. |
| `rrdoctor fix` | Apply safe, idempotent scaffolding for common gaps (`--write` to apply). |
| `rrdoctor plan` | Emit a tool-agnostic fix plan (Markdown or JSON). |
| `rrdoctor prepare` | Write a local AE prep packet: report, plan, appendix, and verification. |
| `rrdoctor verify` | Reproducibility ladder L1/L2/L3; `--command` pins the official quickstart; `--run` actually builds and executes. |
| `rrdoctor appendix` | Generate an ACM Artifact Appendix + ACM/NeurIPS checklist mapping. |
| `rrdoctor badge` | Emit an artifact-readiness badge (Shields.io endpoint or SVG). |
| `rrdoctor mcp` | Run the MCP server (`scan`/`verify`/`appendix` as agent tools). |
| `rrdoctor init` | Write a documented `.rrdoctor.yml`. |
| `rrdoctor list-rules` | List all registered rules. |
| `rrdoctor explain RRD0xx` | Explain a rule and how to remediate it. |
| `rrdoctor doctor` | Self-diagnostics. |
| `rrdoctor --version` | Show the installed package version. |

## Rule categories

Documentation, environment, data, experiments, notebooks, citation, governance, testing,
CI, security, release, and metadata. The full table is in [docs/checks.md](docs/checks.md);
auto-fixable rules are marked there.

## Reproducibility stance

Research Repo Doctor does not claim to prove a paper is reproducible. It checks release
hygiene that makes reproduction possible to attempt. Reports are heuristic and should be
reviewed by maintainers. Generated fixes are starting points and contain placeholders to
complete before release.

## Philosophy

Deterministic first. The scanner is understandable, testable, and useful with no network
access. The core scanner will not add network calls, require a hosted-service API key, or
fabricate adoption metrics. AI is something you bring to act on the output - never a
dependency of the audit itself, and never tied to a single tool.

## Configuration

```yaml
version: 1
profile: standard
paths:
  exclude: [".git", ".venv", "node_modules", "__pycache__"]
thresholds:
  large_file_mb: 50
  large_notebook_output_kb: 1024
rules:
  RRD032:
    enabled: false
  RRD042:
    severity: warning
fail_on: error
```

See [docs/configuration.md](docs/configuration.md).

## Contributing

Contributions are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md),
open a rule request or false-positive report, and include a minimal fixture when possible.

## Security

Do not report suspected credential exposure in a public issue. See [SECURITY.md](SECURITY.md).

## Citation

Use the included [CITATION.cff](CITATION.cff) or cite the version DOI for this
release: [10.5281/zenodo.21289885](https://doi.org/10.5281/zenodo.21289885).
The stable concept DOI,
[10.5281/zenodo.21045161](https://doi.org/10.5281/zenodo.21045161), resolves to
the latest archived release and preserves the complete version lineage.

A JOSS-style draft manuscript is available in [paper/](paper/) for review. It is
not a submitted manuscript and intentionally avoids unverified adoption claims;
formal submission metadata will be updated only when it is true.

```bibtex
@software{research_repo_doctor_2026,
  title = {Research Repo Doctor},
  author = {{Research Repo Doctor Maintainers}},
  version = {0.2.24},
  year = {2026},
  doi = {10.5281/zenodo.21289885},
  url = {https://github.com/Tom409114/research-repo-doctor}
}
```

## License

MIT. See [LICENSE](LICENSE).