Academic code replicator

1. The Core Principle

Academic code replication is an archaeology problem, not a software engineering problem. The fundamental tension that drives every decision in this skill is: You must not change what the experiment computes, but you often must change how it runs. This skill is grounded in real replication sessions: R code OOM-crashing at 78GB, TensorFlow 2.3 refusing to install on ARM64, nested loops taking 95 million iterations, C compilers silently missing. The protocols here are not theoretical best practices — they are patterns distilled from those failures.

2. When To Use / When NOT To Use

Use when: User is working with existing code from a published paper and wants to run it and verify results. Do NOT use when: User wants to RE-IMPLEMENT a paper from scratch (different goal — recommend ml-engineer or domain skill). User has their own original codebase they want to debug (use standard debugging, not this skill). User wants to understand a paper theoretically without running code.

3. Phase Overview

Phase	Name	Goal	Reference Doc
0	Context Detection	Profile user's environment, route correctly	references/context-detection.md
1	Ingestion & Comprehension	Read-only code audit before touching anything	references/phase-1-ingestion.md
2	Environment Construction	Create isolated, working dependency environment	references/phase-2-environment.md
3	Code Adaptation	Safe modifications to make code run on this platform	references/phase-3-adaptation.md
4	Execution & Monitoring	Run safely on available hardware	references/phase-4-execution.md
5	Validation & Documentation	Compare results to paper; document everything	references/phase-5-validation.md

4. Context Detection (Phase 0)

Execute this inline before loading any phase docs.

Step 1 — Detect OS and architecture: Run or ask: What OS? (macOS/Linux/Windows). If macOS, is it Apple Silicon (M1/M2/M3) or Intel? This determines which platform doc to load.

Step 2 — Detect knowledge source about the paper: Ask the user (or infer from context) which of these they have:

• (A) A compiled ARA or knowledge artifact in a knowledge base
• (B) The paper PDF locally
• (C) A URL/DOI to the paper
• (D) Only the code repository URL/path

Load accordingly: A → read ARA. B → read methodology + experiments sections. C → fetch abstract + code link. D → treat code as source of truth.

Step 3 — Detect project structure: Check if user has an existing experiment directory with conventions. If yes, ask: "Do you have a specific folder structure or conventions I should follow?" If no structure exists → propose creating the Minimal Replication Package (MRP).

Step 4 — Check for available skills (optional orchestration): Note which of these skills are available in the user's ecosystem (do not require any of them):

• ara-compiler: Can compile paper into structured knowledge artifact
• distributed-gpu-engineer: Can deploy long-running jobs to SLURM/HPC
• ponytail: Keeps orchestration scripts minimal (YAGNI)

After completing steps 1-4, write a brief Environment Profile to the session's replication log before proceeding.

Environment Profile format (write verbatim in log):

## Environment Profile
- **OS/Arch**: [macOS arm64 / macOS x86 / Linux x86 / Windows / Linux arm64]
- **Paper knowledge**: [ARA / PDF / URL only / Code only]
- **Project structure**: [Existing: {path} / MRP created at: {path}]
- **Available skills**: [list or "none detected"]
- **Platform doc**: [references/platform-{apple-silicon|linux|cluster|windows}.md]
- **Language doc**: [references/lang-{python|r|julia|other}.md]

5. The Minimal Replication Package (MRP)

When the user has no existing structure, create exactly this:

{experiment_name}/
├── REPLICATION_LOG.md    ← Create first. Template below.
├── src/
│   ├── original/         ← Original code goes here. NEVER MODIFIED.
│   └── adapted/          ← All your modifications go here.
└── results/
    ├── tables/
    └── figures/

REPLICATION_LOG.md initial content to write:

# Replication Log: {paper_title}

**Paper**: {paper_title}
**Code source**: {repo_url}
**Replication started**: {YYYY-MM-DD}
**Target results**: [fill after reading paper]

---

<!-- Most recent entries at TOP -->

## {YYYY-MM-DD} Environment Profile
{paste the environment profile output from Context Detection}

6. The Sacred Boundary Principle

The Sacred Boundary Principle: src/original/ contains the authors' code, frozen at the moment of replication. It is NEVER modified. src/adapted/ contains copies of files you need to change. Two years from now, the diff between these directories is your scientific audit trail — proof of exactly what you changed to make the code run, and what you did not touch.

If the user's existing structure uses different directory names, respect those names. The principle is what matters: one directory frozen, one for adaptations.

7. Phase Execution Instructions

1. Always run Phase 0 (Context Detection) inline — do not load a reference doc.
2. Load the phase reference doc at the START of each phase. Use it. Then proceed.
3. Load the language doc when the primary language is confirmed in Phase 1.
4. Load the platform doc once and keep it loaded for Phases 2–4.
5. Do not skip phases. Each phase produces output that the next phase depends on.
6. Write to REPLICATION_LOG.md at the end of every work session, not just at the end of the replication.

8. Skill Bridge Protocol

Bridge 1 — ara-compiler (trigger: after Context Detection, ONLY IF detected as available in Phase 0): Say: "I can compile this paper into a structured knowledge artifact using the ara-compiler skill, which will give me richer context for the replication. Would you like to do that first? (recommended if you plan to replicate multiple papers or want persistent knowledge)" If yes → hand off to ara-compiler with paper PDF/URL → receive ARA → use as Phase 1 input. If no or skill absent → proceed with available knowledge.

Bridge 2 — ponytail (trigger: during Phase 4, when writing orchestration scripts): When creating orchestration scripts (run_all.sh, run_parallel.py, evaluate.py), prefer minimal implementations. If ponytail skill is available, invoke it for script creation. If not, apply the principle manually: shortest code that correctly orchestrates the experiment. No speculative abstractions.

Bridge 3 — distributed-gpu-engineer (trigger: Phase 4, when runtime > 12 hours): Say: "This experiment's estimated runtime exceeds 12 hours on local hardware. I recommend deploying it to a compute cluster. [If skill available:] I can hand this off to the distributed-gpu-engineer skill to set up the SLURM job. [If not:] I'll document the cluster requirements and provide a SLURM template from the platform-cluster reference." Handoff context to provide: experiment directory path, the exact run command, estimated RAM, estimated runtime, language/framework.

Bridge 4 — save-session / Obsidian (trigger: end of Phase 5, ONLY IF detected as available in Phase 0): Say: "Replication complete. Would you like to file the key findings (what worked, what needed adaptation, any deviations) to your knowledge base for future reference?" If Obsidian/save-session available → write structured log entry with links. If not → ensure REPLICATION_LOG.md is comprehensive enough to serve as the permanent record.