# AI Context: REMARK Repository

## Repository Overview
This repository defines and maintains the **REMARK standard** - a specification for creating reproducible computational economics research. REMARK stands for "R[eplications/eproductions] and Explorations Made using ARK".

## Core Purpose
- **Primary Function**: Standardize reproducible computational economics research
- **Problem Solved**: Eliminates the common frustration of downloading economics papers with code that can't be reproduced on different systems
- **Target Audience**: Economics researchers, computational economists, academics working with the Econ-ARK toolkit

## Repository Structure & Key Components

### Documentation Files
- `README.md`: Main project overview and catalog information
- `STANDARD.md`: Technical requirements for REMARK compliance (must-read for implementation)
- `Motivation.md`: Explains why the standard was created (addresses reproducibility crisis in economics)
- `How-To-Make-A-REMARK.md`: Technical instructions for creating and maintaining REMARKs
- `EDITORIAL.md`: Guidelines for editors reviewing REMARK submissions
- `FAQ.md`: Common questions about the project

### Technical Infrastructure
- `cli.py`: Command-line tool for cloning, building, linting, and executing REMARKs
- `myst.yml`: MyST configuration for documentation site generation
- `requirements.txt`: Python dependencies for the CLI tool
- `REMARKs/`: Directory containing metadata files (`.yml`) for each cataloged REMARK

### Content Types
The repository catalogs three types of computational economics projects:
1. **Explorations**: Demonstrations using Econ-ARK/HARK toolkit
2. **Replications**: Attempts to replicate published papers or canonical results 
3. **Reproductions**: Code reproducing ALL results of a paper

## Technical Requirements (REMARK Standard)
For a project to be REMARK-compliant, it must have:
- Tagged GitHub release with semantic versioning
- `reproduce.sh` script that runs all computations
- `binder/environment.yml` with pinned dependencies
- `CITATION.cff` file with bibliographic metadata
- Optional: `reproduce_min.sh` for faster execution (if full version >5 minutes)

## Key Differentiators
- **vs DemARK**: REMARKs can rely on local files/subdirectories with predictable filepaths
- **vs Traditional Papers**: Requires computational reproducibility as core standard

## Automation & Tools
- CLI tool supports parallel processing with `-J` flag
- Automated environment building (conda/docker)
- Automated linting to check standard compliance
- Integration with MyBinder for cloud execution
- MyST-based documentation site generation

## Governance & Quality Control
- Pull request-based submission process
- Editorial review for standard compliance
- Public catalog at econ-ark.org/materials
- Minimal review for successful replications
- Additional scrutiny for replications with discrepancies

## Data Format
REMARK metadata stored as YAML files with fields:
- `name`: Short identifier
- `remote`: GitHub repository URL  
- `title`: Human-readable title
- Additional fields in corresponding markdown files for website display

## Integration Points
- **Econ-ARK website**: Displays catalog at econ-ark.org/materials
- **MyBinder**: Enables cloud execution of REMARKs
- **Conda/Docker**: Supports multiple environment types
- **GitHub**: Uses releases, pull requests, and standard Git workflows

## Success Metrics & Impact
- Addresses reproducibility difficulties in computational economics
- Enables "standing on shoulders of giants" rather than reinventing code
- Promotes transparency and collaboration in economics research
- Reduces time from weeks/months to "touch of a button" for running others' code

## For AI/ML Applications
This standard could be valuable for:
- Training models on reproducible economics research
- Automated analysis of computational methods in economics
- Building datasets of working economic models
- Research into reproducibility practices across disciplines

## Current Status
- Active repository with 20+ cataloged REMARKs
- Established workflow and tooling
- Integration with broader Econ-ARK ecosystem
- Ongoing submissions and maintenance