Tinkering

Overview

Structured experimentation framework. When uncertain about an approach, don't
hack at production code - create an isolated sandbox, try freely, then graduate
successful experiments or discard failed ones cleanly.

Core principle: The output of tinkering is knowledge, not production code.
A successful experiment teaches you how to solve the problem. The actual
implementation happens after, informed by what you learned.

When to Use

Situation	Tinkering?	Why
"Will this library work for our use case?"	Yes	Unknown outcome, need to explore
"Which of these 3 approaches is fastest?"	Yes	Comparing multiple options
"How do I integrate this API?"	Yes	Technical spike, learning-focused
"Add a login button to the header"	No	Clear requirement, use git branch
"Fix the null pointer on line 42"	No	Debugging, not experimenting
"Refactor auth module to use JWT"	Maybe	If approach uncertain, spike first

---

Workflow

Phase 1: Setup Sandbox

Create isolated experiment environment:

# 1. Create experiment directory
mkdir -p _experiments/{experiment-name}

# 2. Add to .gitignore (if not already present)
grep -qxF '_experiments/' .gitignore 2>/dev/null || echo '_experiments/' >> .gitignore

# 3. Create manifest (first time only)
# See MANIFEST.md template below

MANIFEST.md template (create at _experiments/MANIFEST.md):

# Experiment Log

## Active

### {experiment-name}
- **Date**: YYYY-MM-DD
- **Hypothesis**: What we're trying to learn
- **Status**: active
- **Result**: (pending)

## Completed
<!-- Move finished experiments here -->

Rules:

• NEVER modify production files during tinkering
• ALL experiment code goes inside _experiments/{name}/
• Copy source files into sandbox if you need to modify them

---

Phase 2: Hypothesize

Before writing any code, state clearly:

Question : What specific question are we answering?
Success  : How will we know it works?
Time box : Maximum time to spend (default: 30 min)
Scope    : Which files/areas are involved?

Write this in _experiments/{name}/HYPOTHESIS.md or as a top comment.

Example:

Question : Can we replace moment.js with date-fns and reduce bundle size?
Success  : Bundle decreases >20%, all date formatting still works
Time box : 20 minutes
Scope    : src/utils/date.ts, package.json

---

Phase 3: Experiment

Build freely in the sandbox.

Modifying existing code:

# Copy the file(s) you need to change
cp src/utils/date.ts _experiments/date-fns-migration/date.ts
# Edit the copy freely - zero risk to production

New feature exploration:

# Create new files directly in sandbox
touch _experiments/websocket-poc/server.ts
touch _experiments/websocket-poc/client.ts

Library evaluation:

# Minimal test script in sandbox
touch _experiments/redis-eval/test_redis.py
# Use isolated dependencies (venv, local node_modules)

Multi-approach comparison:

_experiments/caching-spike/
  approach-a-redis/
  approach-b-memory/
  approach-c-sqlite/
  COMPARISON.md       # Side-by-side evaluation

Rules during experimentation:

• Stay in sandbox - never touch production files
• Quick and dirty is fine - this is throwaway code
• Document learnings as you go
• Stop at time box, even if incomplete - partial answers are still answers

---

Phase 4: Evaluate

Assess results against the hypothesis.

Checklist:

• Did the experiment answer the original question?
• Does it meet the success criteria from Phase 2?
• Any unexpected side effects or constraints discovered?
• Is the approach feasible for production implementation?
• What's the estimated effort to implement properly?

Update MANIFEST.md:

- **Result**: SUCCESS - date-fns reduced bundle by 34%, all tests pass
- **Status**: graduated
- **Notes**: Need to handle timezone edge case in formatRelative()

Decision:

• Positive result -> Phase 5, Path A (Graduate)
• Negative result -> Phase 5, Path B (Discard)
• Inconclusive -> Extend time box OR try different approach

---

Phase 5: Graduate or Discard

Path A: Graduate (success)

Load reference: references/graduation-checklist.md

Quick summary:

1. Do NOT copy-paste experiment code directly into production
2. Re-implement properly using what you learned
3. Write proper tests for the production implementation
4. Apply code standards (experiment was quick & dirty, production shouldn't be)
5. Reference experiment in commit message for context

Path B: Discard (failed)

Failed experiments are valuable - they tell you what NOT to do.

1. Update MANIFEST.md with failure reason and learnings
2. Delete experiment files: rm -rf _experiments/{name}/
3. Or keep briefly if learnings are worth referencing

---

Phase 6: Cleanup

# Remove completed experiment
rm -rf _experiments/{experiment-name}/

# Update MANIFEST.md - move entry to "Completed" section

MANIFEST.md after cleanup:

## Completed

### date-fns-migration (2025-01-15)
- GRADUATED - Implemented in commit abc123
- Learnings: date-fns 3x smaller, timezone handling needs explicit config

### graphql-evaluation (2025-01-10)
- DISCARDED - Too much overhead for our simple REST API
- Learnings: REST + OpenAPI better fit for <20 endpoints

---

Quick Reference

Setup      ->  mkdir _experiments/{name}, add to .gitignore
Hypothesize ->  Question + success criteria + time box
Experiment  ->  Build in sandbox (never touch production)
Evaluate    ->  Check against success criteria
Graduate    ->  Re-implement properly in production
Cleanup     ->  Remove files, update manifest

Edge Cases

Needs database changes: Use separate test DB or schema prefix. Document in hypothesis.

Needs running server: Run from sandbox, use different port to avoid conflicts.

Multiple concurrent experiments: Each gets own subdirectory. MANIFEST tracks all.

Experiment grows into real feature: Graduate it. Don't let experiments become shadow production code.

Team member needs to see experiment: Push to feature branch (temporarily track _experiments/) or share via patch.