Rigorous Research Assistant

Rigorous Research Assistant is a portable Agent Skill that lets Codex, Claude Code, or another compatible coding agent help carry a researcher-directed project across the full lifecycle:

question selection → literature and novelty → claim design → experiments → execution → result audit → correction or redesign → paper writing → manuscript audit → review → release

It does more than return a plan. In full-cycle mode, it is instructed to inspect the live workspace, create the required artifacts, implement and run permitted work, verify outputs, persist its state, and continue to the next evidence-justified task without waiting for a new prompt after every routine step.

Core principle: engineering readiness and scientific validity are different. Passing tests proves that a pipeline runs; it does not prove a research claim.

The exact reach depends on the host's tools, source access, data, compute, credentials, and the authority granted by the researcher. Within those limits, the Skill can drive the following loop.

The assistant can repeat design → execute → inspect → correct → re-execute → re-inspect when the correction is scientifically legitimate. It is explicitly forbidden to keep rerunning, changing metrics, deleting failures, or rewriting the story merely to obtain a preferred result.

The Skill can turn a real decision letter into a countable, evidence-producing revision program:

raw comment → reviewer intent → validity assessment → required evidence → experiment or analysis → manuscript change → point-by-point response → no-regression audit

It includes an eleven-lens reviewer model distilled into general checks, not paper-specific examples. A formal revision can produce and audit:

• one remediation row and stable response anchor per reviewer or editor point;
• matched-budget ablations, sensitivity studies, model-mismatch tests, operating boundaries, and cost-versus-gain evidence where the criticism requires them;
• an explicit decomposition when revised numbers differ from the submitted ones;
• a point-by-point response that separates answer, evidence, exact manuscript changes, remaining limitation, and regression checks;
• revision highlights that describe what changed instead of repeating the original abstract;
• a concise new cover letter with only human-confirmed policy declarations;
• a final-size figure ledger covering column width, vector/raster choice, effective DPI, embedded fonts, line and marker readability, color independence, crop boxes, axes, captions, and rendered-page inspection.

The deterministic package audit fails closed on missing comments, unfinished templates, unresolved evidence requests, absent response anchors, unverified citation handling, weak raster resolution, or unjustified axis truncation. It does not pretend that structural completeness proves the scientific answer is adequate.

"Full-cycle" means autonomous continuation of authorized research work. It does not mean autonomous scientific authority.

flowchart LR
 A["Recover durable state"] --> B["Choose smallest evidence-producing task"]
 B --> C["Implement or execute"]
 C --> D["Verify raw outputs and gate evidence"]
 D --> E{"Classify outcome"}
 E -->|"Gate passes"| F["Checkpoint and advance"]
 F --> B
 E -->|"Environment or code defect"| G["Repair, regress, regenerate"]
 G --> D
 E -->|"Protocol defect"| H["Version amendment + human approval + fresh evidence"]
 H --> B
 E -->|"Valid scientific failure"| I["Downgrade, defer, or kill"]
 E -->|"Human-only decision"| J["Exact handoff and pause"]

The durable controller records:

• current gate and status;
• active task and last checkpoint;
• evidence paths;
• blockers;
• next action;
• acceptance condition;
• whether an authorized human is required.

This lets a later turn—or another compatible agent—resume from inspectable artifacts instead of reconstructing the project from conversational memory.

The assistant may autonomously handle reversible implementation details inside the signed execution contract. It must stop for decisions that materially change the research:

• final question, interpretation, claims, conclusions, authorship, or submission;
• ethics, consent, license, disclosure, privacy, or external release;
• uploading unpublished material to an external service;
• changing a frozen protocol after confirmatory results were inspected;
• selecting again after a locked test set was exposed;
• material spending, production changes, or destructive cleanup;
• two defensible paths that imply different scientific questions, risks, or conclusions.

Humans do not need to approve routine file naming, local diagnostics, test organization, or equivalent reversible implementation choices that leave the scientific contract unchanged.

Gate states are explicit:

not_started · in_progress · passed · failed · blocked · paused · deferred · killed

A failed gate remains part of the research record. A later discovery can reopen an earlier gate and invalidate every dependent stage without deleting historical artifacts.

• A private-by-default .research/ project control layer.
• Persistent full-cycle state and an append-only research-cycle log.
• Autonomy contract, question-candidate ledger, literature records, claim contract, experiment matrix, protocol-amendment ledger, run ledger, result-facts table, paper claim map, manuscript audit, reviewer remediation, and submission checklist.
• Final-size figure audit, point-by-point response, revision-highlights, and resubmission-cover-letter templates.
• Protocols for question selection, literature, novelty, theory, experimental design, execution, statistics, correction, writing, review, privacy, release, and postmortem.
• Local Python tools to initialize or resume a project, enforce safe gate transitions, audit structure, seal artifacts, verify hashes, and scan releases.
• Human-operated workflows for external AI pre-review services.
• Cross-platform lifecycle tests on Windows and Linux.

The repository includes privacy-safe synthetic tests that verify:

• full-cycle initialization and persistent resume state;
• real Codex and Claude Code installation copies that can initialize and audit a project;
• automatic rollback when a gate is passed without evidence;
• automatic rollback when the human authority contract is incomplete;
• explicit reopening and invalidation of dependent gates;
• fresh held-out validation for an applied protocol amendment;
• preservation of a valid negative scientific outcome as killed, not passed;
• a complete synthetic G0 → G11 run;
• rejection of an unsupported manuscript claim until the major audit finding is resolved.
• rejection of an incomplete response package, unresolved reviewer evidence request, missing response anchor, or unverified final-size figure record.

GitHub Actions runs the lifecycle suite on Windows and Linux with Python 3.11 and 3.13. These tests demonstrate workflow mechanics and fail-closed behavior; they do not certify the scientific validity of a user's project.

• Python 3.10 or newer for the bundled local utilities.
• Codex, Claude Code, or another directory-based Agent Skills host with a SKILL.md entrypoint.
• The data, literature access, compute, tools, and credentials required by the specific project.
• Appropriate human domain expertise, supervision, and authorization.

git clone https://github.com/bsq415/research-rigor-skill.git
cd research-rigor-skill

The installer refuses to overwrite an existing Skill directory.

python install.py --host codex --scope user

Start a full-cycle project:

$research-rigor Work in full-cycle mode on this researcher-directed project.
Recover the live state, complete every reversible and authorized evidence-justified
step, implement and run permitted work, checkpoint artifacts, audit every result,
and stop only at a human-only decision or a documented blocker.

Request a narrower audit:

$research-rigor Audit this workspace only. Report the current gate, verified evidence,
scientific gaps, engineering gaps, blockers, claim downgrades, and exact next action.
Do not mutate the project.

Install for the current user:

python install.py --host claude-code --scope user

Or install for one repository:

python install.py --host claude-code --scope project --project-dir /path/to/project

Start the same full-cycle workflow:

/research-rigor Work in full-cycle mode on this researcher-directed project.
Continue through topic screening, experiment design and execution, result checking,
legitimate correction or redesign, writing, and manuscript audit. Preserve failures
and stop at every human-only boundary.

Claude Code uses the same SKILL.md, references, templates, and scripts as Codex. See platform compatibility.

Initialize:

python skills/research-rigor/scripts/init_research_project.py /path/to/project --mode full-cycle

Inspect resumable state:

python skills/research-rigor/scripts/research_cycle.py status /path/to/project

Run the structural audit:

python skills/research-rigor/scripts/audit_research_state.py /path/to/project

Audit a formal revision or resubmission package:

python skills/research-rigor/scripts/audit_revision_package.py /path/to/project --strict --expected-comments 11

Omit --expected-comments when the decision does not provide a countable set. The command checks coverage, provenance, document completion, and figure records; it does not decide whether a response is scientifically adequate.

See command schemas:

python skills/research-rigor/scripts/research_cycle.py checkpoint --help
python skills/research-rigor/scripts/research_cycle.py transition --help

The structural audit checks records and invariants. It is deliberately not a novelty, theorem, statistics, or scientific-validity oracle.

Rigorous Research Assistant can prepare the exact manuscript hash, privacy and upload checklist, raw-review record, and remediation ledger for a human-operated service such as Stanford Agentic Reviewer. It never uploads a private or unpublished manuscript automatically and never treats an AI score as peer-review authority.

Before any upload, an authorized human must check the service's current privacy, retention, deletion, data-use, and venue-policy terms. Every factual criticism and suggested citation still requires independent verification.

• Bundled scripts process local files and do not upload manuscripts.
• .research/ is private by default.
• Public artifacts should exclude identities, private paths, unpublished results, distinctive unpublished ideas, credentials, and project-specific case material.
• scan_release.py checks common leak patterns and private deny terms without printing matched sensitive values.
• A clean automated scan is not proof of anonymity; a human semantic review remains mandatory.

research-rigor-skill/
├── .github/workflows/validate.yml
├── README.md
├── README.zh-CN.md
├── DISCLAIMER.md
├── LICENSE
├── install.py
├── tests/
└── skills/research-rigor/
 ├── SKILL.md
 ├── agents/openai.yaml
 ├── assets/project-scaffold/
 ├── references/
 └── scripts/

The Skill cannot supply missing subject-matter expertise, lawful data access, ethics approval, experimental resources, independent replication, or truthful external systems. Its structural checks cannot prove a theorem, certify novelty, validate a causal claim, or decide whether a paper deserves acceptance.

All generated code, searches, analyses, statistics, figures, prose, and decisions must be reviewed at the level appropriate to the research risk. Read the full Disclaimer.

Privacy-safe contributions are welcome:

• a general failure mode with a synthetic regression case;
• a stronger evidence, provenance, or manuscript check;
• a domain module that preserves human ownership and fail-closed gates;
• compatibility, documentation, or test improvements.

Do not submit private manuscripts, unpublished project details, personal data, credentials, proprietary datasets, or identifiable case material.

Released under the MIT License.

Rigorous Research Assistant was distilled from generalized workflow lessons across multiple completed, incomplete, failed, and paused research efforts. The public repository contains no private paper content, project-specific results, personal identity, or proprietary case study.