# Explore: Propose a Novel Experiment

## CLI Reference

Run all abreka commands with `uv run abreka <command>`.

**Finalizing the reserved experiment:**
- `uv run abreka exp update {{reserved_exp_id}} --hypothesis "..." --method "..." --tag <tag> --status proposed`  (new direction, no parent)
- `uv run abreka exp update {{reserved_exp_id}} --hypothesis "..." --method "..." --parent <id> --tag <tag> --status proposed`  (extending prior work — rare in exploration)

**Querying experiments:**
- `uv run abreka exp show <id>` — full details: hypothesis, method, metrics, findings
- `uv run abreka exp list --sort metric:val:accuracy` — list sorted by metric
- `uv run abreka exp list --parent <id>` — list children of an experiment
- `uv run abreka exp search "<query>"` — keyword search over hypotheses, methods, findings
- `uv run abreka exp tree` — show the experiment DAG
- `uv run abreka exp diff <id1> <id2>` — compare two experiments side-by-side

**Backlog:**
- `uv run abreka backlog list` — list all open backlog ideas
- `uv run abreka backlog show <id>` — full details of a backlog idea
- `uv run abreka backlog resolve <id> --exp <new_exp_id>` — mark a backlog idea as resolved after creating its experiment

**Project Wiki** (durable cross-experiment knowledge — see "Project Wiki" section below):
- `uv run abreka wiki list` — list every wiki page
- `uv run abreka wiki show <slug>` — read a page in full
- `uv run abreka wiki search "<query>"` — keyword/regex search across pages

{{wiki_index}}

## Research Goal

{{goal}}

## Primary Metric

{{primary_metric}} ({{metric_direction}})

## Branch Overview

{{branch_overview}}

{{focused_branch_summary}}

## Experiment History

{{experiment_context}}

{{focus_constraint}}

## Pending Backlog Ideas

{{backlog_context}}

{{guidance}}

## Your Task

You are in **exploration mode**. Your job is NOT to improve the current best result. Instead, propose an experiment that explores a **fundamentally different approach** that the research has not yet tried.

**Reserved experiment ID:** `{{reserved_exp_id}}`

You must populate this already-reserved experiment and set its status to `proposed`. Do **not** create another experiment.

Use the branch overview above to see which territories the existing search has already colonized — those are the ones to avoid. Health classifications of `plateauing`, `noisy`, or `declining` across the board are the clearest justification for a brand-new branch. Skim the wiki for assumptions that current experiments share — exploration often comes from challenging one of them.

Your proposal must include:
1. **Hypothesis**: A clear, testable statement about why this different approach might work. Ground it in domain knowledge or reasoning, not in extrapolation from existing results.
2. **Method**: A concise description of the experimental approach. Describe it from scratch — this should be understandable without reference to prior experiments.
3. **Parent experiments**: Almost certainly **none**. Exploration experiments forge new paths. Only set a parent if you are deliberately reviving an abandoned or low-performing line that deserves a second look from a different angle.
4. **Tags**: Include `explore` as a tag, plus a few keywords for the approach.

### What makes a good exploration experiment

- It tries a technique, architecture, or paradigm that is **absent from the experiment history** above.
- It is motivated by domain knowledge, literature, or creative reasoning — not by extrapolating from the current best.
- It could plausibly achieve a breakthrough even if the current approach is stuck.
- It is different enough that its success or failure teaches something new about the problem, not just about hyperparameter sensitivity.

### What to AVOID

- Do NOT extend the current best experiment or any high-performing line.
- Do NOT make incremental changes (learning rate tweaks, layer count adjustments, regularization tuning) to existing approaches.
- Do NOT re-test ideas that prior findings already ruled out.
- If you find yourself writing `--parent`, reconsider. Exploration experiments should almost never have a parent.

### Strategy

Look at the experiment history and ask:
- What broad categories of approach have NOT been tried at all?
- Are there well-known techniques in the literature that are absent here?
- Could the problem be reformulated or decomposed differently?
- Is there a completely different family of models, algorithms, or representations to try?
- What assumptions do all existing experiments share — and what if one of them is wrong?

### How to work

- Your working directory is the **project root**. All project source files, tests, and experiment code are under `.` — use paths like `src/...`, `tests/...`, etc. Do NOT use `..` to navigate to a parent directory.
- Review the experiment history above to understand what has been tried.
- If you need more detail on a specific experiment, use `uv run abreka exp show <id>`.
- You may read project source files to understand the current codebase.

### Optional EDA

If a relevant data question would meaningfully sharpen this proposal, do a small amount of exploratory data analysis before finalizing. Save any artifacts under `abreka/experiments/{{reserved_exp_id}}/artifacts/eda/`. Keep EDA scoped to what informs *this* proposal. The evaluate stage will later promote durable EDA findings into the wiki.

After deciding, finalize the reserved experiment:
```bash
uv run abreka exp update {{reserved_exp_id}} --hypothesis "Your hypothesis here" --method "Brief method" --tag explore --tag <tag1> --tag <tag2> --status proposed
```
