--- name: research-executor description: "Execute research experiments using TDD methodology. Pops plans from .claude/plans/research_tasks/, implements with smoke/unit/integration tests, and documents results to results.md. Use when: (1) executing the next experiment from the queue, (2) executing a specific plan by number, (3) running an ad-hoc research idea with TDD." user_invocable: true --- # Research Executor Execute research experiments using Test-Driven Development (TDD). ## Plan Queue Plans are stored in `.claude/plans/research_tasks/plan-*.md`. ### Pop and Execute 1. **List plans**: `ls .claude/plans/research_tasks/plan-*.md` 2. **Select plan**: Default is `plan-1.md`, or specify `plan-N` 3. **Move to executed**: ```bash mkdir -p .claude/plans/research_tasks/executed mv .claude/plans/research_tasks/plan-{N}.md .claude/plans/research_tasks/executed/{YYYY-MM-DD}_{name}.md ``` 4. **Renumber remaining plans** sequentially (plan-2 → plan-1, plan-3 → plan-2, etc.) If no plans exist, ask user for an ad-hoc research idea. ## Execution Workflow ### Phase 1: Setup - Parse hypothesis, variables, success criteria from plan - Create directory: ``` experiments/{experiment_name}/ ├── README.md ├── notebook.ipynb # Primary deliverable ├── tests/ │ ├── smoke/ │ ├── unit/ │ └── integration/ ├── src/ └── results/ └── figures/ # All generated plots ``` ### Phase 2: Smoke Tests - Test data loading, API calls, metric computation - Implement minimal code to pass - Run: `uv run pytest experiments/{name}/tests/smoke/ -v` ### Phase 3: Unit Tests - Test each component (preprocessing, features, model, evaluation) - TDD: Red → Green → Refactor - Run: `uv run pytest experiments/{name}/tests/unit/ -v` ### Phase 4: Integration Tests - Test full pipeline end-to-end - Run on sampled data first - Run: `uv run pytest experiments/{name}/tests/integration/ -v` ### Phase 5: Finalize - Run full experiment - Create Jupyter notebook deliverable (see below) - Document results (see Results Documentation) - Commit changes ## Jupyter Notebook Deliverable **Required**: Every experiment MUST produce a Jupyter notebook at `experiments/{name}/notebook.ipynb`. ### Notebook Structure ``` 1. Header & Setup - Experiment title, date, hypothesis - Import statements and configuration 2. Data Loading & Exploration - Load experimental data - Show sample data, shapes, dtypes - Basic statistics (describe(), value_counts()) 3. Implementation - Core experiment code with explanatory markdown cells - Each major step in its own cell for re-runnability 4. Results & Visualizations - All figures generated inline (use %matplotlib inline) - Statistical tests with p-values, confidence intervals - Summary tables of key metrics 5. Conclusions - Key findings from the experiment - Link to hypothesis: supported/refuted/inconclusive - Next steps or follow-up questions ``` ### Requirements - All cells must be executed (outputs saved in notebook) - Use markdown cells to explain each section - Save figures both inline AND to `experiments/{name}/results/figures/` - Include reproducibility info: random seeds, package versions - Final cell: print summary statistics and status ## Results Documentation Create `results.md` in `.claude/plans/research_tasks/executed/` alongside the executed plan: ```markdown # Experiment: {name} **Date**: {YYYY-MM-DD} **Plan**: {original plan path} **Status**: success | failure | partial ## Hypothesis {from plan} ## Test Results - Smoke: X/Y passing - Unit: X/Y passing - Integration: X/Y passing ## Findings {key observations, metrics, conclusions} ## Artifacts - **Notebook**: `experiments/{name}/notebook.ipynb` (primary deliverable) - Code: `experiments/{name}/src/` - Figures: `experiments/{name}/results/figures/` - Data: `experiments/{name}/results/` ``` ## Code Standards - Type hints for all functions - Docstrings for public APIs - Reproducible random seeds (document in README) - Use `uv run ruff check` and `uv run ruff format` before commits