ai-research-reproduction

SKILL.md

ai-research-reproduction

Purpose

Use this as the Rigor Reproduce compatible skill slug for README-first deep
learning repository reproduction. The installed slug remains
ai-research-reproduction for compatibility. The skill guides the agent toward
a minimal trustworthy run with auditable evidence; it should not micromanage
implementation details that the model can infer from the repository.
Reproduction is not "make it run by changing anything"; it means faithfully
reading the README, environment, weights, datasets, and documented commands,
then recording results and deviations.

Start from the shared operating principles in
../../references/agent-operating-principles.md, then load
../../references/research-rigor-principles.md and
../../references/deep-learning-experiment-principles.md when scientific
meaning, comparability, or experiment details are at stake.
Fit

Use this skill when all are true:

The target is an AI code repository with a README, scripts, configs, or
documented commands.

The request spans multiple trusted phases such as intake, setup, execution,
training verification, analysis, paper-gap resolution, and reporting.

The desired result is a small reproducible target, not broad experimentation.

Do not use this skill for paper summaries, generic environment setup, isolated
repo scanning, standalone command execution, open-ended research design, or
explicit candidate-only exploration.

Trusted Target Selection

Choose the smallest target that can honestly demonstrate repository-grounded
reproduction:

documented inference

documented evaluation

documented training startup or partial verification

full training only after explicit user confirmation

Treat README guidance as the primary reproduction intent. Use repository files
to clarify the README, not to silently replace it. When the README and paper
conflict, record the conflict and use paper-context-resolver only for the
narrow reproduction-critical gap.

Workflow

Read the README and nearby repo signals.

Use repo-intake-and-plan to extract documented commands and candidate
targets.

Select and justify the minimum trustworthy target.

Use env-and-assets-bootstrap only for target-specific environment,
checkpoint, dataset, and cache assumptions.

Use analyze-project only when structure, insertion points, or suspicious
implementation patterns need read-only clarification.

Use minimal-run-and-audit for documented inference, evaluation, smoke, or
sanity execution.

Use run-train instead when the selected trusted target is training startup,
short-run verification, full kickoff, or resume.

Pause for human review before fuller training claims or any change that could
alter dataset, split, checkpoint, preprocessing, metric, loss, model
semantics, or result interpretation.

Write the standardized outputs and give a concise final note in the user's
language when practical.

Patch Boundary

Prefer no repository edits. If edits are needed, keep them conservative and
auditable:

Try command-line arguments, environment variables, path fixes, dependency
version fixes, or dependency-file fixes before code changes.

Reproduction fixes are allowed when needed, but they must not be hidden. State
what changed, why it was necessary, whether it changes scientific meaning,
and whether it affects comparability with the paper, README, or baseline.

Avoid changing model architecture, core inference semantics, training logic,
loss functions, or experiment meaning.

If repository files must change, create a branch named
repro/YYYY-MM-DD-short-task, keep verified patch commits sparse, and record
README-fidelity impact in PATCHES.md.

See references/patch-policy.md.

Outputs

Always target repro_outputs/:

SUMMARY.md
COMMANDS.md
LOG.md
SCIENTIFIC_CHANGELOG.md
COMPARABILITY_REPORT.md
status.json
PATCHES.md   # only if patches were applied

Use the templates under assets/ and the field rules in
references/output-spec.md.

Put the shortest high-value summary in SUMMARY.md.

Put copyable commands in COMMANDS.md.

Put process evidence, assumptions, failures, and decisions in LOG.md.

Put scientific meaning and change effects in SCIENTIFIC_CHANGELOG.md.

Put comparison anchors and protocol deviations in COMPARABILITY_REPORT.md.

Put durable machine-readable state in status.json.

Put branch, commit, validation, and README-fidelity impact in PATCHES.md when needed.

Distinguish verified facts from inferred guesses.

Reference Loading

Load references/language-policy.md when writing human-readable outputs.

Load ../../references/research-rigor-principles.md before making
comparability, contribution, or research-result claims.

Load ../../references/deep-learning-experiment-principles.md when dataset,
split, metric, checkpoint, training, or evaluation details matter.

Load references/research-safety-principles.md before protocol-sensitive
decisions.

Load references/patch-policy.md before modifying repository files.

Keep specialized logic in sub-skills, scripts, templates, or references rather
than expanding this entrypoint.