# Deep Iris Analysis

A 24-step branched DAG: statistical exploration of Fisher's *Iris* dataset
with R-rendered figures, three-method outlier consensus, conditional
parametric vs non-parametric inference, classification baselines, and a
sensitivity rerun on cleaned data.

Used as the reference trace for "what a mature trace folder looks like".

## Layout

```
iris-analysis/
├─ trace.json         The static plan: step DAG, input declarations,
│                      asset contracts. Read this first.
├─ README.md           ← you are here
├─ memory.md           Cross-run accumulated knowledge (gotchas, decisions).
│
├─ data/
│   └─ iris.csv        Canonical input. Read-only; treat as a fixture.
│
├─ references/         Background notes the steps cite.
│
├─ steps/<step_id>/    One folder per step — owns everything tied to it.
│   ├─ STEP.md         Contract: what reads what, writes what; impl hints.
│   └─ scripts/        (optional) reference implementations (<plot>.R).
│
└─ scripts/            Shared R plot library — one script per figure.
    ├─ _theme.R        Slate palette + ggplot theme.
    ├─ <plot>.R        Honors $TRACE_OUTPUT_DIR for write target.
    └─ run_all.R       Driver — render every plot at once.
```

The example ships a `build.sh` and a `fixtures/` directory one level up (next
to `template/`). `build.sh` replays the full pipeline through the CLI, using
the pre-generated artifacts in `fixtures/` (regenerated by `fixtures/generate.R`;
not the source of truth — `scripts/` is) so the live demo runs fast. Each run
writes `runs/<run_id>/` with state.json, replies/, and per-step output folders,
owned by the per-trace `.git`.

## How a step grows over time

Fresh step → just a STEP.md. As runs surface what works, the folder accumulates:

1. **STEP.md** — defines the contract (what it reads + writes).
2. **A reference implementation** — `analyze.py` / `<plot>.R` / `run.sh`.
3. **Prompts / templates** — if the step is AI-executed, the prompt that
   has worked best.
4. **Memory** — gotchas surfaced by past runs live in `memory.md`.
5. **Tools** — if multiple steps share a helper, it lifts to `scripts/`.

The trace folder is a git repo; every CLI write is one commit, so the
evolution of each artifact is recoverable.

## Theme

`scripts/_theme.R` defines the slate palette mirroring the frontend's
Tailwind scale (`slate-900` … `slate-100` + status accents). Every plot
script sources it. Default output: 800 × 500 PNG at 144 dpi.

## Rendering one figure

```bash
TRACE_OUTPUT_DIR=runs/<run_id>/feature_distributions \
TRACE_IRIS_CSV=data/iris.csv \
  Rscript scripts/dist_kde.R
```

## R packages

`ggplot2`, `scales`, `dplyr`, `tidyr`. Install these in your R environment and
make sure `Rscript` is on your `PATH` (or point `$RSCRIPT` at a specific one).
