Theory to Algorithm Workflow

A worked example of using coding agents, executable research, and precommitted validation gates to turn established theory into versioned algorithms.

The repository is for researchers and engineers who need to make model changes auditable: assumptions are named, candidates are replayable, negative results remain visible, and publication cannot silently turn a failed experiment into a promoted algorithm.

The workflow

1. Define a measurable estimand.
2. State the relevant theory and assumptions.
3. Make an executable, versioned baseline.
4. Introduce one candidate that removes or tests one assumption.
5. Freeze a validation gate before examining held-out evidence.
6. Produce deterministic evidence from immutable inputs and explicit seeds.
7. Record promotion or non-promotion without rewriting history.
8. Publish the reasoning, code, evidence, and decision together.

See the lifecycle and validation lanes.

Complete case study

The vocabulary-estimation example defines receptive knowledge of lemma–surface-form pairs in a fixed pool.

• stratified-beta-binomial-v1 became the implementation target.
• continuous-pair-frequency-logistic-v2 tested whether continuous frequency could replace eight independent strata.
• V2 improved aggregate measures but failed precommitted worst-cell coverage, worst-cell error, and test-length checks. It was not promoted; v1 remains the target.

The case-study index links the contract, executable articles, immutable evidence, and tests.

Quick start

git clone --recurse-submodules \
  https://github.com/jamiepratt/theory-to-algorithm-workflow.git
cd theory-to-algorithm-workflow
python3 .agents/scripts/research_workflow.py validate

Preview the configured article with the workflow-owned local preview:

.agents/scripts/vocabulary_preview.sh

Pass a source path relative to the Civitas src/ directory to choose an article explicitly. The wrapper injects this case study's preview behavior without changing Civitas's shared Clay entry point or project defaults. Inside the submodule, clojure -M:clay remains the standard contributor workflow. Use the reported http://localhost:<port> origin consistently. Hot reload and linked-article navigation preserve that origin so Quarto's origin-scoped light/dark preference persists.

Run the configured vocabulary tests through aliases injected by the workflow repository. They coexist with any aliases in Civitas's shared deps.edn:

.agents/scripts/vocabulary_tests.sh clj
.agents/scripts/vocabulary_tests.sh cljs

Use the repository-local skills for repeatable operations:

• $preview-latest-research-article
• $publish-research-prs
• $review-research-prs

Adapt this workflow

Fork or copy the repository, replace the case-study documentation, then edit .agents/research-workflow.json. Configure repository IDs and roles, submodule ownership, article mapping, commands, and browser policy. The three skills contain no case-specific paths or logic; they validate and consume that profile. See the adaptation guide.

Limits

This is one worked case study, not proof that every research question fits one model family or gate. Synthetic validation cannot replace representative human data. Coding agents improve traceability and iteration speed but do not supply scientific authority, choose an estimand, or justify a threshold by themselves. Clojure, Clay, Quarto, Civitas, and Git submodules are example technologies, not workflow requirements.

Root-owned material is MIT licensed. The Civitas submodule retains its own license and history.