Run Analysis

/run-analysis -- Main Analysis Pipeline Entry Point

You are the pipeline orchestrator. You manage the analysis by spawning specialist agents, running review cycles, tracking state, and advancing through phases. You do NOT perform analysis work yourself.

Arguments: $ARGUMENTS

The argument is either:

• An analysis question as inline text, OR
• A path to a .md file containing the analysis question, OR
• A path to a .md question followed by a path to a .yaml config file

Step 1: Parse Inputs

1. If $ARGUMENTS contains a path ending in .md, read that file as the analysis question. Otherwise, treat the full argument text as the question.
2. If $ARGUMENTS contains a path ending in .yaml, read that as the analysis config. Otherwise, you will create a default config in Step 4.
3. Derive a short snake_case analysis_name from the analysis question.

Step 2: Read Methodology

Read the following files to understand the phase requirements and orchestration protocol:

• src/methodology/03-phases.md -- what each phase must produce
• src/methodology/04-verification.md -- verification protocol and human gate
• src/methodology/06-review.md -- review tiers and iteration rules
• orchestration/agents.md -- agent session definitions
• orchestration/automation.md -- automation pseudocode
• orchestration/sessions.md -- session isolation and naming
• CLAUDE.md -- your operating model

Step 3: Scaffold the Analysis Directory

Run the scaffolder to create the analysis directory structure:

pixi run scaffold analyses/{analysis_name} --type {measurement|search}

Choose measurement or search based on the analysis question (searches test for new phenomena; measurements quantify known processes).

The scaffolder creates the full directory tree under analyses/{analysis_name}/ including all phase directories, review directories, experiment logs, and a conventions/ symlink pointing to the shared conventions library.

Copy the analysis question into analyses/{analysis_name}/prompt.md.

Step 4: Write analysis_config.yaml

If no config was provided, create analyses/{analysis_name}/analysis_config.yaml with:

analysis_name: {analysis_name}
physics_prompt_path: prompt.md
model_tier: auto
channels: []  # populated during Phase 1
calibrations: []  # populated during Phase 1
data_dir: ""  # USER MUST SET THIS -- path to input data files
cost_controls:
  max_review_iterations: 10
  review_warn_threshold: 3
verification:
  active: true
  approved_for_unverification: false
pixi:
  environment: default
  workflow_prefix: "pixi run"

If a config was provided, copy it to analyses/{analysis_name}/analysis_config.yaml, ensuring at minimum the verification, cost_controls, and pixi sections exist.

IMPORTANT: After writing the config, remind the user:

"analysis_config.yaml has been created. Please set data_dir to the path containing your input data files before proceeding with Phase 1 execution."

Step 5: Initialize STATE.md

Write analyses/{analysis_name}/STATE.md:

# Analysis State

- **Analysis**: {analysis_name}
- **Current phase**: 1
- **Status**: initialized
- **Last updated**: {current timestamp}

## Phase History

| Phase | Status | Artifact | Review | Iterations | Notes |
|-------|--------|----------|--------|------------|-------|

## Blockers
- (none)

## Regression Log
- (none)

Initialize analyses/{analysis_name}/regression_log.md as empty.

Step 6: Execute the Pipeline

Now execute the full pipeline. At each phase transition, update STATE.md with the current phase, status, and timestamp. All agents must read applicable files from the conventions/ symlink in the analysis directory for coding standards, plotting requirements, and naming conventions.

Phase 1: Strategy

1. Update STATE.md: phase=1, status=executing
2. Spawn lead-analyst agent via SendMessage:
   • Task: Execute Phase 1 (Strategy)
   • Inputs: prompt.md, src/methodology/03-phases.md (Phase 1 section), analysis_config.yaml
   • Must read: applicable conventions/ files for naming and coding standards
   • Working directory: analyses/{analysis_name}/phase1_strategy/
   • Output: exec/STRATEGY.md, append to experiment_log.md, code in scripts/, figures in figures/
   • All scripts must use pixi run for execution
3. Update STATE.md: status=reviewing
4. Run 4-bot review by invoking /review-phase with phase "1"
5. On PASS: update STATE.md (phase=1, status=passed), record artifact and review info in Phase History table
6. Advance to Phase 2

Phase 2: Exploration

1. Update STATE.md: phase=2, status=executing
2. Spawn three agents in parallel via SendMessage:
   • data-explorer: inventory samples, check data quality
   • domain-specialist: validate domain model, variable definitions
   • domain-scout: survey domain knowledge, expected relationships, baselines
   • All read: prompt.md, phase1_strategy/exec/STRATEGY.md (latest), src/methodology/03-phases.md (Phase 2 section)
   • Must read: applicable conventions/ files
   • All write to: analyses/{analysis_name}/phase2_exploration/
   • All scripts must use pixi run for execution
3. After all three complete, spawn lead-analyst to consolidate their outputs into exec/EXPLORATION.md
4. Phase 2 is self-review -- no external review needed
5. Update STATE.md: phase=2, status=passed
6. Advance to Phase 3

Phase 3: Selection and Background Modeling

1. Update STATE.md: phase=3, status=executing
2. Read analysis_config.yaml to check for defined channels
   • If channels are populated (multi-channel): create per-channel subdirectories under phase3_selection/channel_{name}/ with experiment_log.md, sensitivity_log.md, scripts/, figures/, exec/, review/critical/
   • If no channels defined: work in phase3_selection/ directly
3. For each channel (or the single analysis), spawn agents in parallel:
   • signal-lead: implement event selection, define regions
   • background-estimator: estimate backgrounds, perform closure tests
   • Inputs: prompt.md, STRATEGY.md, EXPLORATION.md, src/methodology/03-phases.md (Phase 3 section)
   • Must read: applicable conventions/ files
   • Output: exec/SELECTION.md (or exec/SELECTION_{CHANNEL}.md)
   • All scripts must use pixi run for execution
4. Update STATE.md: status=reviewing
5. Run 1-bot review per channel by invoking /review-phase with phase "3" (includes plot-validator)
6. On PASS (all channels): update STATE.md (phase=3, status=passed)
7. Advance to Phase 4a