kwongfuk/codex-skills/repro-record-workflow

Repro Record Workflow

Keep reproduction work and record-keeping coupled:

1. Execute a concrete subtask.
2. Validate outcome quickly (logs, test, job status, artifact path).
3. Append one concise record entry to CODEX_RECORD.md.

Workflow

1. Locate record file:

• Use repository root CODEX_RECORD.md.
• If missing, create it from record-template.md.

1. Split request into small subtasks:

• Keep each subtask independently verifiable.
• Prefer one observable output per subtask (job id, file diff, command result).

1. Apply storage policy before execution:

• keep repository files under /home focused on code, configs, CODEX_RECORD.md, and standard lightweight experiment results
• keep datasets, caches, model weights, checkpoints, raw intermediates, and other large artifacts under /scratch
• if a result directory is large, store the primary artifact on scratch and record the absolute scratch path in Evidence

1. Execute subtask:

• Apply environment/config/code changes.
• For training launchers or checkpoint logic, also apply exact-training-resume-guard.
• Run minimal verification.

1. Update record immediately:

• Use scripts/update_codex_record.py.
• One entry per completed/failed subtask.
• Include blockers and next action if failed.

1. Repeat:

• Never batch many subtasks into one record entry.

Record Rules

1. Use timestamped entries (script default).
2. Include these fields:

• Task
• Status
• Summary
• Evidence
• Next

1. Keep entries short and factual.
2. Use absolute paths/job ids in Evidence.
3. If a training run is only restartable from model weights rather than exactly resumable, record that limitation explicitly instead of calling it a resume checkpoint.

Commands

Create or append entry:

python ~/.codex/skills/repro-record-workflow/scripts/update_codex_record.py \
  --record /path/to/repo/CODEX_RECORD.md \
  --task "Run smoke preflight on A100 node" \
  --status failed \
  --summary "Import failed in trainer package" \
  --evidence "Job 10087183; log: /path/gui_g2_smoke-10087183.out" \
  --next "Patch missing import and resubmit smoke test"

Create record file if missing:

cp ~/.codex/skills/repro-record-workflow/references/record-template.md /path/to/repo/CODEX_RECORD.md