This file defines guidance for humans or AI agents extending the pillChoice experiment.

The goal is not abstraction or scale — it’s to enable fast, observable growth experiments inside Val Town.

pillChoice is a deliberately small experiment:

• one entry point
• two paths
• immediate instrumentation

Any changes should preserve:

• speed of iteration
• clarity of user intent
• observability of outcomes

If a change makes the experiment harder to reason about, it’s probably the wrong change.

Avoid:

• heavy routing frameworks
• complex client state management
• premature abstractions
• background jobs unless they demonstrate a clear growth loop

This project should remain understandable in under 5 minutes.

Good next experiments include:

• adding a third path (e.g. “neutral pill”) and comparing conversion
• logging additional activation metrics (time on page, scroll depth)
• changing copy and measuring pill selection rate
• adding a lightweight follow-up action after /blue (e.g. delayed email)

• Every meaningful user action should emit an event.
• Events should be append-only.
• Prefer adding new event types over modifying existing ones.
• Schema changes should create new tables if needed.

• All persistence must use Val Town std/sqlite.
• Side effects (email, webhook) should happen server-side only.
• Failures in side effects must not break the user flow.

• Code should favor readability over cleverness.
• UI copy should be concise, slightly playful, and developer-native.
• This is a growth experiment, not a portfolio site.

Optimize for:

1. Shipping quickly
2. Measuring outcomes
3. Minimizing complexity

If unsure, choose the simplest possible implementation.