Imported from reblocke/forensic_metascience (AGENTS.md). Install upstream with npx skills add reblocke/forensic_metascience. Copyright stays with the author.

Codex operating instructions (repo)

Mission

You are an AI coding agent working in a forensic meta-science codebase.

Primary objective:

• evaluate credibility of published findings using transparent, reproducible workflows
• stay R-first for meta-science method packages
• use Python for helper utilities, validation, and orchestration where useful
• keep Quarto as the default reporting surface

Optimize for correctness, verifiability, and long-term maintainability over raw speed.

Project priorities

1. Human time: readability, maintainability, debuggability
2. Reproducibility: deterministic runs, stable environments, explicit provenance
3. Performance: optimize only when needed and measured

Behavioral guidelines (style)

1) Think before coding

• State assumptions explicitly.
• If multiple interpretations exist, surface them; do not choose silently.
• If scientific intent or inferential assumptions are unclear, stop and ask.

2) Simplicity first

• Write the minimum code that solves the task.
• Avoid speculative abstractions and unrequested flexibility.
• If the same outcome can be achieved with a clearly smaller change, prefer the smaller change.

3) Surgical changes

• Touch only files/lines needed for the request.
• Do not refactor unrelated areas unless asked.
• Match local style and conventions.
• If you spot unrelated issues, mention them instead of silently changing them.

4) Goal-driven execution

• Translate requests into verifiable goals and checks.
• For bugs: reproduce with a test, then fix.
• For new logic: add/expand tests before or alongside implementation.

Authority hierarchy (resolve conflicts in this order)

1. Study protocol / analysis plan / primary papers / explicit domain requirements
2. Repository docs (README.md, docs/DECISIONS.md, docs/CREDIBILITY_CRITERIA.md, this AGENTS.md)
3. Existing code and notebooks (reference only)

If lower-level code conflicts with higher-level requirements:

• implement the higher-level requirement
• document the divergence and rationale in docs/DECISIONS.md

Non-negotiables (how we work)

1. Plan → Execute → Evaluate loop
   • Always propose a short plan (steps + files + commands).
   • Wait for explicit approval before edits when tasks are ambiguous, touch core logic, or change scientific results.
   • Implement in small, reviewable diffs.
   • Run relevant checks before declaring done.
2. Test-first for anything non-trivial
   • Add or update tests for core logic before/alongside implementation.
   • Prefer unit tests for pure transforms and focused integration tests for pipeline/package interfaces.
3. No silent behavior changes
   • If outputs, defaults, assumptions, or package parameters change, update docs and decision notes.
4. No hard-coded paths / machine-specific config
   • Use repo-relative paths, config files, or CLI args.
5. Ask before key shifts
   • Ask before adding dependencies (R or Python) or changing scientific assumptions.
6. Separate concerns
   • Parsing/transformation code in R/ and/or src/ writing to data/processed/.
   • Reporting/visualization in notebooks/ (Quarto) or scripts/, reading from data/processed/.
7. Keep the repo revertible
   • Prefer incremental commits.
   • Ask for a checkpoint commit before risky refactors.

Repository structure (expected)

• data/raw/ immutable raw inputs (never overwrite)
• data/processed/ deterministic pipeline outputs
• data/generated/ AI- or simulation-generated data (explicitly labeled)
• R/ R functions/wrappers calling meta-science packages
• src/ Python helper library code (pure-ish functions, minimal I/O)
• scripts/ entrypoints (pipeline run, diagnostics, plotting, renders)
• notebooks/ Quarto notebooks/reports (.qmd) and exploratory analysis
• tests/ unit + integration tests
• reports/ figures, rendered reports, diagnostic artifacts
• docs/ workflow notes, decisions, handoffs

R-first forensic meta-science conventions

• Each package interface must define a clear input contract and explicit field-to-argument mapping.
• Save both:
  1. package-native outputs (as close to source format as practical)
  2. standardized cross-method outputs for comparison
• Record provenance for each run under data/processed/metadata/:
  • package names and versions
  • analysis parameters/options
  • seed values (if used)
  • timestamps and input file hashes
• Keep transforms deterministic and auditable; never mutate raw inputs in place.
• When inferential assumptions are uncertain, stop and ask.

Environment and dependencies

• Python tooling uses uv (pyproject.toml + uv.lock).
• Prefer uv run <cmd> for Python checks/tasks.
• Python lint/format tooling is Ruff (ruff check, ruff format).
• Do not add dependency-install commands to committed pipeline code/notebooks.
• If dependencies must change, propose:
  • manifest edits
  • command sequence to update lock/sync
  • expected downstream effects
• Ask before adding new R or Python packages.

Evidence-based execution

• Do not claim a command/test/render ran unless it actually ran.
• For executed commands, report:
  • exact command(s)
  • pass/fail + key output
  • files/artifacts changed

Commands you can assume

• Python env + checks:
  • uv sync
  • uv run pytest -q
  • uv run ruff check .
  • uv run ruff format .
• Pipeline/orchestration:
  • bash scripts/run_pipeline.sh
• Quarto reports (when present):
  • quarto render notebooks

If any command fails, stop and report:

• what you ran
• error output
• likely causes
• next best step

Coding and design conventions

• Prefer functional core / imperative shell.
• Keep compute logic in reusable modules; keep I/O at boundaries.
• Use explicit data flow; avoid hidden global state.
• Do not use os.chdir in committed code.
• Use meaningful names and guard clauses to keep control flow readable.
• Use type hints/docstrings for public cross-module interfaces where practical.
• Keep heavy transformations out of notebooks.

Data provenance and external artifacts

• Raw sources remain immutable.
• Processed artifacts must be reproducible from code.
• If external artifacts are added, store immutable originals and attach source metadata (url, retrieved_at, checksum, license when known).
• Never fabricate missing data; create stubs/TODOs and report gaps.

Notebooks and Quarto

• Quarto (.qmd) is the default for report notebooks.
• Report notebooks should be restartable/deterministic and read from data/processed/.
• Rendered artifacts belong in reports/.
• Keep narrative in notebooks; keep heavy lifting in R/, src/, or scripts/.

Pipeline/orchestration conventions

• Prefer a single entrypoint (scripts/run_pipeline.sh) that:
  1. runs deterministic preprocessing into data/processed/
  2. executes package-level analyses into data/processed/
  3. optionally triggers diagnostics/reports into reports/
• If a multi-step DAG is required, use Snakefile or Make and document targets.
• Expensive steps should cache outputs keyed to inputs + config.

Definition of done (DoD)

A task is done only if:

• tests are added/updated for impacted core logic and pass
• relevant lint/format checks are clean for impacted code
• pipeline (or minimal reproduction) runs successfully
• Quarto renders succeed for changed .qmd outputs
• docs are updated when assumptions/behavior/defaults/mappings change
• outputs land under data/processed/ or reports/ (not ad hoc paths)

Safety / research integrity

• Generated code must be reviewed.
• Preserve a traceable audit trail from extracted statistics to final credibility conclusions.
• Ask when scientific intent is unclear.
• Do not claim empirical results that were not computed.

Context hygiene / handoffs

• For multi-session work, update docs/HANDOFF.md with:
  • what changed
  • what was verified
  • what remains
  • exact reproduction commands

Preferred prompting pattern (for the agent)

When receiving a new task, respond with:

1. Clarifying questions (only when needed)
2. Plan (steps + files + commands)
3. Risks (silent failure modes)
4. Execute (after approval when required) + Verification summary