Implementation
A setup to support an AI-assisted ORDERly workflow
An ORDERly project setup
A GitHub template repository: github.com/andreashandel/mds-project-template
- Organized
-
The template provides a detailed file and folder structure to organize the project
- Recorded
-
Git/GitHub history, generated outputs, AI-use logs, and project notes preserve the path taken
- Documented
-
Markdown and Quarto files, folder READMEs, documented code, and AI policy explain what to do and why
- Executable
-
Scripts and Quarto files regenerate processed data, analyses, figures, tables, and products
- Reproducible
-
A modeling and data analysis project that can be reproduced from the raw data to all finished products.
The project structure gives each part a role
The main path runs data/ → code/ → results/ → products/; the other folders and root files provide stable inputs and guidance.
![A row of four boxes joined by arrows: data (inputs, derived data), code (workflow stages), results (generated outputs), and products (deliverables for the audience). Below sit three supporting boxes: assets (stable support), ai (policy, summary, log), and root files (readme.md, usage.md).]()
Separate raw, derived, private, and large data
raw-data/ — Original input; preserve it unchangedprocessed-data/ — Cleaned or transformed data generated by codeprivate-data/ — Restricted material kept in an approved locationlarge-files/ — Material too large for ordinary Git and GitHub use
Track changes with Git, guard what you share
- Commit small, meaningful changes; push to back up and to share
- Start private; go public later after checking data, outputs, license, and authorship
- Keep sensitive data out via
.gitignore
- Nothing above roughly 20 MB; use the ignored
large-files/ folders instead
Code follows the stages of the analysis
Each stage should have recognizable inputs, outputs, and instructions.
![Four boxes joined by arrows: data-processing (raw to processed), data-exploration (checks, summaries), modeling-analysis (models, results), and figures-tables (final outputs). A wide box below reads utilities: optional support for repeated helper logic.]()
Keep generated outputs separate from everything else
results/-
Code-generated model objects, intermediate outputs, figures, and tables
products/-
Reports, manuscripts, supplements, presentations, posters, and apps
assets/-
References, PDFs, schematics, and other stable supporting material
ai/-
AI policy, project context, guidance, and meaningful-use records
Running the workflow
code/data-processing/processing-code.r → data/processed-data/code/data-exploration/eda-code.r → results/output/code/modeling-analysis/statistical-analysis.r → results/output/code/figures-tables/make-tables.r → results/tables/code/figures-tables/make-figures.r → results/figures/quarto render the products you need → products/
Never hand-edit raw data, or results/products — change the code and rerun.
The template ships a working example
Run it end to end once, then replace it piece by piece with your own project.
- Data and code
-
data/raw-data/example-data.xlsx and five short R scripts, one per workflow stage
- Generated results
-
results/output/, results/tables/, and results/figures/, all rebuilt from code
- Finished products
-
report.qmd, manuscript.qmd with supplement, an example presentation, and a poster stub
Every number and figure in those products can be traced back to a script.
AI can support project work
- Code
Write, document, refactor, and debug project code
- Literature
Help search, summarize, and organize background material
- Writing
Draft or improve reports, manuscripts, and presentations
- Documentation
Keep code, outputs, and documentation aligned
How AI plugs into this project
- Run it inside the repository
-
Use an agentic tool that can read and write project files and run code
- Point it at the documents first
-
readme.md, usage.md, agents.md, and code-guidelines.md carry the project rules
- Bound what it may do
-
ai/ai-use-policy.md states what AI may touch, and what must never leave the project
- Let it record its work
-
ai/ai-use-log.md is written by the AI; ai/project-summary.yml keeps it oriented
- Keep changes reviewable
-
Ask for small steps, then rerun affected scripts and re-render affected products
AI can support ORDERly habits
Things worth asking your assistant to do:
- Organized
-
“Check that every file sits in the folder its role calls for.”
- Recorded
-
“Summarize what changed today and why, and log your own contribution.”
- Documented
-
“Update the READMEs and usage notes to match what the code now does.”
- Executable
-
“Run this script in a clean session and fix what breaks.”
- Reproducible
-
“Trace this figure back to the data it came from and show me the path.”
An ORDERly project is easy to work with
- Current you can work efficiently
- Future you can recover the reasoning
- Collaborators can inspect and extend the work
- AI can assist appropriately
- Others can understand and recreate the stated result
