experiment-init

Experiment Init — Set Up an Experiment

You are creating a structured experiment to validate an idea, test a hypothesis, or explore an unknown. Experiments are cheap, time-boxed, and throwaway — their only purpose is learning.

Principle: An experiment that takes longer than a day is a sprint, not an experiment. Keep it ruthlessly small.

Tone

Practical and focused. Experiments are about speed and learning, not polish. Help the user define the smallest thing that would actually answer their question.

Setup Process

Step 1: Detect or Create Experiment Structure

Check for experiments/ at the project root (or configured path).

If it doesn't exist, create it:

experiments/
├── _methodology/
│   └── experiment-workflow.md    # From references/experiment-methodology.md
├── _template/
│   ├── EXPERIMENT.md             # From references/experiment-template.md
│   └── code/
│       └── .gitkeep
└── archived/
    └── .gitkeep

This is a one-time setup — only happens on the first experiment. After that, the structure exists and is reused.

If experiments/ already exists, skip straight to creating the experiment.

Step 2: Understand the Experiment

Ask the user (or extract from context):

1. What are we testing? "What's the specific question this experiment answers?"
2. Standalone or feature-linked? "Is this tied to a feature hypothesis, or just exploring an idea?"
3. Name: Suggest a short kebab-case name based on the question

If coming from /feature-validate, the context is already clear — don't re-ask what they already answered.

Step 3: Create the Experiment Folder

Create experiments/[experiment-name]/:

[experiment-name]/
├── EXPERIMENT.md     # From template, filled with user's answers
├── code/
│   └── .gitkeep
└── .gitkeep          # RESULTS.md created after running

If linked to a feature, add a feature field in EXPERIMENT.md frontmatter pointing to the feature folder.

Step 4: Fill EXPERIMENT.md

Walk the user through the template interactively. The key sections:

1. Core Question: "What specific thing are we trying to validate? One sentence."
2. Hypothesis: "What do you expect to find?"
3. Method: "How will we test this? Be specific — what do we build, run, or measure?"
4. Baseline: "What's the current state we're comparing against?"
5. Success Criteria: "What result means proceed? What means pivot? What means stop?"
6. Timeline: "How long should this take? (Hours, not days.)"

Push for specificity on success criteria — "it feels better" is not a criterion.

Step 5: Add to CLAUDE.md (first time only)

If this is the first experiment in the project, append to CLAUDE.md:

### Experiments (validation & proof of concepts)
Experiments live under `experiments/[name]/` with EXPERIMENT.md and optional code/.
- Lifecycle: init → run → results
- Time-boxed: hours, not days
- Methodology: `experiments/_methodology/experiment-workflow.md`
- Skills: `/experiment-init`, `/experiment-run`, `/experiment-results`

Step 6: Next Steps

"Experiment set up. Ready to run it?

• /experiment-run [name] — Build and execute the experiment
• Come back later — the experiment is saved and ready"

Behavioral Rules

Do:

• Create the full experiments/ structure on first use (methodology, template, archived)
• Push for a specific, measurable core question
• Time-box aggressively — suggest hours, push back on days
• Link to the feature if coming from /feature-validate

Don't:

• Create experiments/ during docs-setup — only on demand
• Let vague success criteria slide — "it works" is not good enough
• Over-design the experiment structure — keep it minimal
• Confuse experiments with features — experiments are throwaway, features are permanent

References

• references/experiment-methodology.md — Experiment process documentation
• references/experiment-template.md — EXPERIMENT.md template