---
name: experiment
description: Run a structured experiment in a sandboxed .lab/ directory. Follows the THINK -> TEST -> REFLECT cycle with time-boxing and results tracking. Use when testing hypotheses about performance, architecture, or approach.
---

# Experiment Skill

Run a structured, time-boxed experiment to test a hypothesis. All work happens in `.lab/` (gitignored) so experiments never pollute the main codebase.

## When to Use

- Comparing libraries or approaches
- Benchmarking performance (bundle size, query speed, rendering)
- Evaluating architecture options before committing
- Testing algorithm parameters or configurations
- Any "what if" question that needs empirical data

## Workflow

### 1. Setup

Create a numbered experiment directory:

```bash
mkdir -p .lab/NNN-short-description/
```

Where `NNN` is the next sequential number (check `.lab/` for existing experiments). Use a short, descriptive name (e.g., `001-auth-lib-comparison`, `002-query-optimization`).

### 2. THINK: Write the Hypothesis

Create `.lab/NNN-short-description/hypothesis.md` with:

```markdown
# Experiment NNN: [Title]

**Date:** YYYY-MM-DD
**Session:** N
**Time box:** [15-30 minutes]

## Hypothesis
[What you expect to happen and why]

## Success Metric
[One specific, measurable metric — e.g., "response time improves by >20%",
"bundle size decreases by >10KB", "test passes in <200ms"]

## Method
[Exact steps to test the hypothesis]

## Baseline
[Current measurement of the success metric, if known]
```

### 3. TEST: Run the Experiment

- Write test code directly in the experiment directory (`.lab/NNN/test.ts`, `.lab/NNN/benchmark.py`, etc.)
- Each test iteration should produce a measurable result
- Log intermediate results as you go — do not hold them only in context
- Stay within the time box. If you run out of time, record partial results

### 4. REFLECT: Write Results

Create `.lab/NNN-short-description/results.md` with:

```markdown
# Results: Experiment NNN

## Outcome
[CONFIRMED / REJECTED / INCONCLUSIVE]

## Data
[Raw measurements, comparison tables, before/after numbers]

## Analysis
[What the data means, why the hypothesis was confirmed/rejected]

## Decision
[KEEP / DISCARD / INVESTIGATE FURTHER]
- KEEP: The change is an improvement. Log to PATTERNS.md or DECISIONS.md and apply to codebase.
- DISCARD: The change is not an improvement. Log what was learned to PATTERNS.md.
- INVESTIGATE FURTHER: Results are promising but inconclusive. Note what additional testing is needed.

## Learnings
[What was learned that applies beyond this specific experiment]
```

### 5. Feed Back

- If KEEP: Create an entry in `agent-learnings/PATTERNS.md` or `agent-learnings/DECISIONS.md` referencing the experiment
- If DISCARD: Add a brief note to `agent-learnings/PATTERNS.md` so future agents do not re-run the same experiment
- If INVESTIGATE FURTHER: Add to `agent-learnings/IMPROVEMENTS.md` with a reference to the experiment directory

## Rules

- **Time box:** Default 15-30 minutes per experiment. State the time box in the hypothesis. Respect it.
- **Isolation:** All experiment files live in `.lab/`. Never modify main codebase files during an experiment.
- **One variable:** Change one thing at a time. If you need to test multiple variables, run multiple experiments.
- **Measure first:** Record the baseline measurement before making changes.
- **No cleanup required:** `.lab/` is gitignored. Old experiments can stay for reference or be deleted freely.

## Directory Structure

```
.lab/
|-- 001-auth-lib-comparison/
|   |-- hypothesis.md
|   |-- results.md
|   |-- benchmark.py
|   +-- data/
|-- 002-query-optimization/
|   |-- hypothesis.md
|   |-- results.md
|   +-- test.ts
+-- ...
```