<!-- Experimentation skill - create, run, and document technology experiments -->

experimentation mode: HANDS-ON DISCOVERY

when this skill is active, you systematically create and run experiments.
this is a comprehensive guide to learning by doing with minimal risk.


PHASE 0: EXPERIMENT ENVIRONMENT SETUP


verify experiment infrastructure

  <terminal>mkdir -p ~/experiments</terminal>
  <terminal>ls -la ~/experiments</terminal>

  <terminal>mkdir -p ~/experiments/active</terminal>
  <terminal>mkdir -p ~/experiments/completed</terminal>
  <terminal>mkdir -p ~/experiments/failed</terminal>

  <terminal>mkdir -p ~/experiments/templates</terminal>


create experiment template

  <create><file>~/experiments/templates/README.md</file><content># [experiment-name]

purpose: [clear statement of what we're testing]
hypothesis: [what we expect to learn]
status: [planned/in-progress/completed/failed/abandoned]

## metadata

created: <date>
started: <date>
completed: <date>
estimated effort: [hours]
actual effort: [hours]

## context

why this experiment:
  - [what sparked interest]
  - [problem it might solve]

questions to answer:
  - [question 1]
  - [question 2]
  - [question 3]

## experiment design

variables:
  - independent: [what we change]
  - dependent: [what we measure]
  - controlled: [what stays constant]

success criteria:
  - [criterion 1]
  - [criterion 2]

## setup

steps:
  [1] [setup step 1]
  [2] [setup step 2]
  [3] [setup step 3]

dependencies:
  - [package/tool 1]
  - [package/tool 2]

## execution

phase 1: [name]
  - [what we did]
  - [what we observed]
  - [time spent]

phase 2: [name]
  - [what we did]
  - [what we observed]
  - [time spent]

## findings

what worked:
  - [working aspect 1]
  - [working aspect 2]

what didn't:
  - [failing aspect 1]
  - [failing aspect 2]

surprises:
  - [unexpected discovery 1]
  - [unexpected discovery 2]

## measurements

quantitative data:
  - [metric 1]: [value]
  - [metric 2]: [value]

qualitative observations:
  - [observation 1]
  - [observation 2]

## code

key files:
  - [file]: purpose
  - [file]: purpose]

## conclusions

hypothesis validated: [yes/no/partial]

answers to questions:
  - [question 1]: [answer]
  - [question 2]: [answer]
  - [question 3]: [answer]

recommendations:
  - [recommendation 1]
  - [recommendation 2]

## next steps

if continuing:
  - [next experiment]

if adopting:
  - [integration steps]

if abandoning:
  - [why not useful]

## lessons learned

technical:
  - [technical lesson 1]
  - [technical lesson 2]

process:
  - [what we'd do differently]
  - [what worked well]

## artifacts

screenshots: [link]
logs: [link]
data: [link]

## references

documentation: [link]
inspiration: [link]
related experiments: [link]
</content></create>


verify tools for experiments

  <terminal>which git</terminal>
  <terminal>which node</terminal>
  <terminal>which python</terminal>
  <terminal>which docker</terminal>

initialize version control for experiments:

  <create><file>~/experiments/.gitignore</file><content># node_modules
node_modules/

# python
__pycache__/
*.pyc
venv/
.venv/

# environment
.env
.env.local

# ide
.vscode/
.idea/

# logs
*.log

# build artifacts
dist/
build/

# temp files
*.tmp
.DS_Store
</content></create>

  <terminal>cd ~/experiments && git init</terminal>


PHASE 1: EXPERIMENT INITIATION


step 1: define experiment hypothesis

answer:
  - what specific question are we answering?
  - what do we expect to find?
  - how will we know if it worked?

example hypotheses:
  - "hypothesis: [tool] can reduce build time by [X]%"
  - "hypothesis: [framework] reduces boilerplate by [X]%"
  - "hypothesis: [pattern] simplifies [problem]"


step 2: scope the experiment

define boundaries:
  - minimal viable experiment: what's the smallest test that answers the question?
  - timebox: maximum hours to invest before re-evaluating
  - stop conditions: what would make us stop early?

example scoping:
  - minimal: hello world + one realistic use case
  - timebox: 2 hours initial, then re-evaluate
  - stop: if setup takes > 30 minutes, abort


step 3: create experiment directory

  <terminal>mkdir -p ~/experiments/active/<experiment-name></terminal>

  <terminal>cd ~/experiments/active/<experiment-name> && cp ~/experiments/templates/README.md .</terminal>

  <terminal>cd ~/experiments/active/<experiment-name> && git init</terminal>


step 4: initialize project structure

for javascript/node:
  <terminal>cd ~/experiments/active/<experiment-name> && npm init -y</terminal>

  <create><file>~/experiments/active/<experiment-name>/package.json</file><content>{
  "name": "<experiment-name>",
  "version": "0.0.1",
  "description": "experiment: [purpose]",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "test": "echo \"no tests specified\" && exit 0"
  },
  "keywords": ["experiment"],
  "author": "marco",
  "license": "MIT"
}
</content></create>

for python:
  <terminal>cd ~/experiments/active/<experiment-name> && python -m venv venv</terminal>
  <terminal>cd ~/experiments/active/<experiment-name> && source venv/bin/activate && pip install --upgrade pip</terminal>

  <create><file>~/experiments/active/<experiment-name>/requirements.txt</file><content># experiment dependencies
# add packages as needed
</content></create>

  <create><file>~/experiments/active/<experiment-name>/.python-version</file><content>3.11
</content></create>


step 5: commit initial structure

  <terminal>cd ~/experiments/active/<experiment-name> && git add .</terminal>
  <terminal>cd ~/experiments/active/<experiment-name> && git commit -m "init: initialize experiment"</terminal>


PHASE 2: MINIMAL VIABLE IMPLEMENTATION


step 1: hello world

create the simplest possible example:

  <create><file>~/experiments/active/<experiment-name>/index.js</file><content>
// hello world for <tech>
// purpose: verify basic setup

console.log('<tech> hello world');
</content></create>

  <terminal>cd ~/experiments/active/<experiment-name> && npm install <package></terminal>

  <terminal>cd ~/experiments/active/<experiment-name> && npm start</terminal>

verify it runs:
  [ ] no errors
  [ ] expected output
  [ ] understand what happened


step 2: add one realistic use case

implement the simplest real scenario:

  <create><file>~/experiments/active/<experiment-name>/example.js</file><content>
// realistic use case 1
// purpose: test actual functionality

const <Tech> = require('<tech>');

async function main() {
  // setup
  const instance = new <Tech>();
  
  // execute
  const result = await instance.doSomething();
  
  // verify
  console.log('result:', result);
}

main().catch(console.error);
</content></create>

  <terminal>cd ~/experiments/active/<experiment-name> && node example.js</terminal>


step 3: measure baseline

document performance/complexity:

  <create><file>~/experiments/active/<experiment-name>/benchmark.js</file><content>
// baseline measurement
// purpose: measure performance/complexity

const <Tech> = require('<tech>');

console.time('operation');
const result = <Tech>.method();
console.timeEnd('operation');

console.log('memory:', process.memoryUsage());
console.log('result:', result);
</content></create>

  <terminal>cd ~/experiments/active/<experiment-name> && node benchmark.js</terminal>


step 4: document initial findings

update experiment readme:

  <edit><file>~/experiments/active/<experiment-name>/README.md</file><find>## execution</find><replace>## execution

phase 1: hello world
  - setup time: [X] minutes
  - errors encountered: [none/list]
  - first run success: yes/no

phase 2: realistic use case
  - implementation time: [X] minutes
  - worked as expected: yes/no
  - unexpected behavior: [description]

## execution</replace></edit>

  <terminal>cd ~/experiments/active/<experiment-name> && git add .</terminal>
  <terminal>cd ~/experiments/active/<experiment-name> && git commit -m "feat: implement minimal example"</terminal>


PHASE 3: ITERATIVE EXPLORATION


step 1: expand to multiple use cases

add 2-3 more examples:

  <create><file>~/experiments/active/<experiment-name>/examples/use-case-2.js</file><content>
// use case 2: [description]
// testing: [what we're testing]

const <Tech> = require('<tech>');

// implementation
</content></create>

  <create><file>~/experiments/active/<experiment-name>/examples/use-case-3.js</file><content>
// use case 3: [description]
// testing: [what we're testing]

const <Tech> = require('<tech>');

// implementation
</content></create>


step 2: stress test

push boundaries:

  <create><file>~/experiments/active/<experiment-name>/stress-test.js</file><content>
// stress test
// purpose: find limits and edge cases

const <Tech> = require('<tech>');

async function stressTest() {
  console.log('starting stress test...');
  
  // test 1: large input
  console.log('test 1: large input');
  const largeInput = /* generate large data */;
  console.time('large');
  const largeResult = <Tech>.process(largeInput);
  console.timeEnd('large');
  
  // test 2: many requests
  console.log('\ntest 2: concurrent requests');
  const promises = [];
  for (let i = 0; i < 100; i++) {
    promises.push(<Tech>.process(i));
  }
  await Promise.all(promises);
  console.log('completed 100 concurrent requests');
  
  // test 3: edge cases
  console.log('\ntest 3: edge cases');
  const edgeCases = [null, undefined, '', [], {}];
  for (const testCase of edgeCases) {
    try {
      const result = <Tech>.process(testCase);
      console.log(`${testCase}: ${result}`);
    } catch (e) {
      console.log(`${testCase}: ERROR - ${e.message}`);
    }
  }
}

stressTest().catch(console.error);
</content></create>

  <terminal>cd ~/experiments/active/<experiment-name> && node stress-test.js</terminal>


step 3: compare with alternatives

if applicable, test competing tools:

  <create><file>~/experiments/active/<experiment-name>/comparison/alternative-a.js</file><content>
// alternative a implementation
// same use case as <tech>

const AlternativeA = require('alternative-a');

// implement same logic
</content></create>

  <create><file>~/experiments/active/<experiment-name>/comparison/compare.js</file><content>
// comparison benchmark
// purpose: compare <tech> vs alternatives

const <Tech> = require('<tech>');
const AlternativeA = require('alternative-a');

console.log('comparing implementations...\n');

console.log('<tech>:');
console.time('<tech>');
<Tech>.run();
console.timeEnd('<tech>');

console.log('\nAlternative A:');
console.time('alternative-a');
AlternativeA.run();
console.timeEnd('alternative-a');
</content></create>

  <terminal>cd ~/experiments/active/<experiment-name> && node comparison/compare.js</terminal>


step 4: document learnings

update readme with findings:

  <edit><file>~/experiments/active/<experiment-name>/README.md</file><find>## findings</find><replace>## findings

what worked:
  - [feature 1]: worked well, intuitive api
  - [feature 2]: performed as expected

what didn't:
  - [issue 1]: confusing error messages
  - [issue 2]: missing documentation

surprises:
  - [unexpected 1]: [discovery]
  - [unexpected 2]: [discovery]

## findings</replace></edit>


PHASE 4: EVALUATION AND DECISION


step 1: evaluate against criteria

review original hypothesis:

  - did we answer our questions?
  - did we learn what we expected?
  - was it worth the time?

score the technology:

  ease of setup: [1-10]
  documentation quality: [1-10]
  api design: [1-10]
  performance: [1-10]
  community support: [1-10]
  overall: [X]/50


step 2: decision framework

adopt if:
  - solves real problem
  - easy to integrate
  - well maintained
  - clear benefit over current solution

experiment further if:
  - promising but needs more exploration
  - uncertain about long-term viability
  - competing alternatives unclear

abandon if:
  - doesn't solve problem
  - too complex for benefit
  - poor documentation
  - unmaintained


step 3: create decision document

  <create><file>~/experiments/active/<experiment-name>/DECISION.md</file><content># Experiment Decision: <experiment-name>

date: <date>
decision: [adopt/experiment-further/abandon]

## summary

experimented with: [technology]
time invested: [X] hours
hypothesis: [original hypothesis]

## evaluation

### what we learned

positive findings:
  - [positive 1]
  - [positive 2]

negative findings:
  - [negative 1]
  - [negative 2]

### scoring

criteria                score    notes
---------------------- ------   -----
ease of setup           [X]/10   [notes]
documentation           [X]/10   [notes]
api design              [X]/10   [notes]
performance             [X]/10   [notes]
community               [X]/10   [notes]
---------------------- ------   -----
total                   [X]/50

## decision

[adopt/experiment-further/abandon]

reasoning:
  - [reason 1]
  - [reason 2]
  - [reason 3]

## next steps

if adopting:
  - [integration step 1]
  - [integration step 2]
  - target project: [which project]

if experimenting further:
  - [what to try next]
  - [when to re-evaluate]

if abandoning:
  - [why not useful]
  - [alternative approaches]

## lessons

for marco:
  - [lesson 1]
  - [lesson 2]

for future experiments:
  - [what we'd do differently]
</content></create>


step 4: archive or move

if completed:

  <terminal>mv ~/experiments/active/<experiment-name> ~/experiments/completed/</terminal>

if failed:

  <terminal>mv ~/experiments/active/<experiment-name> ~/experiments/failed/</terminal>

update experiment registry:

  <edit><file>~/experiments/registry.md</file><find>## completed experiments</find><replace>- [<experiment-name>](completed/<experiment-name>/README.md) - [summary] - <date>
## completed experiments</replace></edit>


PHASE 5: DOCUMENTATION AND SHARING


step 1: create summary report

  <create><file>~/knowledge/experiments/<experiment-name>-summary.md</file><content># <experiment-name> Summary

experiment: <experiment-name>
completed: <date>
decision: [adopt/abandon]

## what we tested

[brief description of technology/experiment]

## key findings

working:
  - [finding 1]
  - [finding 2]

not working:
  - [finding 1]

## recommendations

for marco:
  - [recommendation 1]
  - [recommendation 2]

for others:
  - [general insight]

## code examples

```javascript
// most useful snippet
```

## resources

experiment location: ~/experiments/[completed/failed]/<experiment-name>/

related knowledge:
  - [link 1]
  - [link 2]
</content></create>


step 2: update knowledge base

if adopting:

  <create><file>~/knowledge/technologies/<tech>-guide.md</file><content># <tech> Usage Guide

adopted: <date>

## quick start

install:
  ```bash
  npm install <package>
  ```

basic usage:
  ```javascript
  const <Tech> = require('<tech>');
  // code
  ```

## patterns we use

pattern 1: [name]
  ```javascript
  // example
  ```

pattern 2: [name]
  ```javascript
  // example
  ```

## gotchas

  - [gotcha 1]
  - [gotcha 2]

## marco's projects using this

  - [project 1]: [how used]
  - [project 2]: [how used]

## related experiments

  - [<experiment>](~/experiments/completed/<experiment>/)
</content></create>


step 3: share with community (optional)

create gist or blog post if valuable:

  <terminal>gh gist create ~/experiments/completed/<experiment-name>/DECISION.md -d "experiment: <experiment-name>"</terminal>


PHASE 6: EXPERIMENT CHECKLIST


before starting:
  [ ] clear hypothesis defined
  [ ] scope and timebox set
  [ ] success criteria established
  [ ] stop conditions identified

during experiment:
  [ ] hello world works
  [ ] at least one realistic use case implemented
  [ ] baseline measurements taken
  [ ] notes taken at each step
  [ ] commits made regularly

after experiment:
  [ ] findings documented
  [ ] decision made
  [ ] lessons learned captured
  [ ] knowledge base updated
  [ ] experiment archived


PHASE 7: MANDATORY EXPERIMENTATION RULES


while this skill is active, these rules are MANDATORY:

  [1] ALWAYS START WITH HYPOTHESIS
      experiments must answer specific questions
      random exploration wastes time

  [2] TIMEBOX EVERY EXPERIMENT
      set time limits before starting
      re-evaluate at time limit

  [3] START MINIMAL
      hello world first
      then realistic use case
      then expand if valuable

  [4] DOCUMENT AS YOU GO
      don't wait until the end
      capture insights when fresh
      commit frequently

  [5] MEASURE SOMETHING
      qualitative observations are good
      quantitative data is better
      both together is best

  [6] COMPARE WITH ALTERNATIVES
      understanding relative value
      requires comparison
      not just absolute assessment

  [7] ARCHIVE PROPERLY
      completed → ~/experiments/completed/
      failed → ~/experiments/failed/
      keep context for future reference

  [8] EXTRACT LESSONS
      failure is learning
      document what didn't work
      it's as valuable as successes

  [9] MAKE DECISIONS
      don't just experiment forever
      adopt, continue, or abandon
      move forward

  [10] SHARE KNOWLEDGE
      update marco's knowledge base
      make findings discoverable
      connect to related topics


FINAL REMINDERS


experiments are for learning

you're not building production code
you're building understanding


fail fast, fail forward

quick failure = saved time
documented failure = shared knowledge


minimal is powerful

hello world → realistic case → explore
stop at each stage and evaluate
don't over-invest early


now go build something and learn from it.