---
name: quanterlab-project-structure
description: How a piece of research on QuanterLab stays legible to the person who returns to it in a month. Use when starting a study, naming projects and runs, deciding what to save, or preparing work so that someone else can re-run it. Triggers on requests to organise research, set up a project, clean up saved work, or explain what was tried.
---

# QuanterLab project structure

The property everything rests on: a result someone else can re-run from the record alone. Everything below serves that.

## One project per question

A project answers one question and holds one walk. A second question, or the same question on a second universe, is a second project. When several projects feed one paper, they are declared as a family on the paper's host project, with the count of everything that was walked; the paper then lives on the host and reports every member.

Do not put variants of a rule into one project as forks unless the study is registered as comparative with named arms. A comparative study has two arms and one variable between them; three variables is three studies.

## Naming that says what the run was

A name states the design, not the date and not the mood. `Drawdown cap 20 percent, nine sector SPDRs, equal weight, monthly reselect` can be read in a month. `test_v3_final_final` cannot. The rule: universe, the mechanism that varies, the holding or rebalance rule, the benchmark if it is not the obvious one.

Windows inside a walk are named by their anchor date; the platform does this. Do not rename them.

## The record of what was tried

The family size in a deflation is only truthful if the failures are counted. Keep every arm that died, every configuration that was abandoned, every window that was excluded, in the same record as the survivors:

- A registered hypothesis that was run and lost is a result; it stays.
- A configuration that was tried on the canvas and never registered is a trial too; write it into the project's notes with its outcome in one line.
- An excluded window is printed as excluded with its reason; it is never filled and never quietly dropped from the count.

The write-up reports the count of everything, and the count matches the record.

## Which configurations are saved, and which are scratch

Saved: every registered hypothesis (the platform seals it), every compiled study, the canvas that produced a result you will quote, and any custom primitive a study uses (the registration freezes its source and hash).

Scratch: a canvas you built to learn how a primitive behaves, a run you started to check data coverage, an idea you abandoned before it ran. Scratch is deleted or marked scratch the same day; a month later nobody can tell the two apart.

## What a run needs to be re-runnable by someone else

- The circuit, node by node, with every parameter, as registered. The platform stores it; do not rely on a screenshot.
- The anchor of every window and the plan (universe, step, duration, in-sample years, research type, arms).
- The data rule: point-in-time membership or current, the price source, the cost model.
- Every custom primitive's source at the version that ran, which the seal provides.
- The benchmark and its construction (total return or price, rebased where).
- The trial count and the family, if any.
- The claim as written before the run, and the result as logged, not as remembered.

If any of these lives only in a chat transcript, it is not recorded. Put it in the project's notes or the paper.

## Returning after a month

The test of the structure: open the project cold and answer, in under a minute, what question it asked, what was fixed before the run, what was tried, what came back, and what the next decision is. If the answers are not on the record, the structure has failed and the work is repaired before it continues.