white-room

# The White Room

An omnipresent deep planning system for AI-assisted development.

## The Problem

AI coding tools get you to 60% (the skeleton) then chaos ensues. The White Room pushes to 95% through explicit phases, depth enforcement, and adversarial validation.

## The Promise

**By the end of a White Room session, anyone can build the project without asking a single clarifying question.**

---

## Quick Start

```bash
# In any project, start a White Room session
/white-room-enter

# Check your progress
/white-room-status

# Continue working
/white-room-next

# When done, export execution-ready artifacts
/white-room-export
```

---

## The Four Phases

| Phase | Focus | Goal | Output |
|-------|-------|------|--------|
| **SKELETON** (25%) | WHAT | Capture everything | Vision, Users, Scope, Features |
| **ANATOMY** (25%) | HOW | Define structure | Data Model, APIs, Architecture |
| **PHYSIOLOGY** (35%) | WHAT-IF | All behaviors | Error Handling, Edge Cases |
| **STRESS** (15%) | VALIDATE | Try to break it | Stranger Test, Gauntlet |

---

## Commands

| Command | Purpose |
|---------|---------|
| `/white-room-enter` | Start new or resume existing session |
| `/white-room-status` | Show full progress dashboard |
| `/white-room-next` | Continue from current state (auto-loops) |
| `/white-room-deepen` | Push current feature deeper |
| `/white-room-export` | Generate execution artifacts |

### User Overrides
- `pause` - Save checkpoint and stop gracefully
- `stop` - Force stop (warns if incomplete)
- `skip [feature]` - Mark as intentionally skipped
- `later [item]` - Move to backlog

---

## Directory Structure

### Global (System Files)
```
~/.claude/plugins/local-marketplace/white-room/
├── agents/              # Persona subagents (10 total)
│   ├── white-room-voice.md         # Orchestrator
│   ├── white-room-stranger.md      # Zero-context reviewer
│   ├── white-room-architect.md     # System design
│   ├── white-room-challenger.md    # Devil's advocate
│   ├── white-room-chaos.md         # Failure scenarios
│   ├── white-room-security.md      # Threat modeling
│   ├── white-room-business.md      # Business viability
│   ├── white-room-user-advocate.md # Speaks AS the user
│   ├── white-room-dreamer.md       # Visionary
│   └── white-room-realist.md       # Pragmatic
├── engine/              # Core logic
│   ├── phase-gates.md   # Validation for phase transitions
│   ├── depth-drill.md   # The 6 questions for every operation
│   └── momentum.md      # Auto-continue rules
├── hooks/               # Lifecycle hooks
│   ├── on-session-start.sh
│   ├── on-pre-compact.sh
│   ├── on-stop.sh
│   └── on-user-prompt.sh
├── skills/              # Obra integration
│   └── white-room.md
└── templates/           # Initialization templates
    ├── SESSION-STATE.template.json
    ├── FEATURE.template.json
    └── CLAUDE-MD-SNIPPET.md
```

### Per Project (Session State)
```
$PROJECT/
├── .white-room/
│   ├── SESSION-STATE.json    # Current state (survives everything)
│   └── CHECKPOINTS.log       # Recovery log
└── docs/white-room/
    ├── 00-VISION.md          # What and why
    ├── 01-USERS.md           # Personas
    ├── 02-SCOPE.md           # In/out/never
    ├── 03-FEATURES.md        # Feature specs
    ├── 04-USER-FLOWS.md      # All branches
    ├── 05-ARCHITECTURE.md    # System design
    ├── 06-DATA-MODEL.md      # Entities
    ├── 07-API-CONTRACTS.md   # Endpoints
    ├── 08-UI-SPEC.md         # Screens
    ├── 09-SECURITY.md        # Threats
    ├── 10-TESTING.md         # Strategy
    ├── 11-DEPLOYMENT.md      # How to ship
    ├── 12-RISKS.md           # Identified risks
    ├── 13-DECISIONS.md       # ADRs
    ├── 14-GLOSSARY.md        # Terms
    ├── 15-TASK-BREAKDOWN.md  # Ready to build
    └── exports/              # Generated artifacts
```

---

## The Depth Drill

For EVERY operation in PHYSIOLOGY phase:

1. **Network Failures** - What if connection drops?
2. **Double Actions** - What if user clicks twice?
3. **Unexpected Data** - What if API returns garbage?
4. **Timing Issues** - What if it takes 10x longer?
5. **Data Integrity** - What if input is malformed?
6. **Permission Changes** - What if auth expires?

---

## Key Behaviors

### Auto-Continue (Momentum Engine)
White Room keeps moving forward unless:
- User says "pause" or "stop"
- Unresolvable blocker encountered
- All phases complete

### Phase Gates
Cannot advance until gates are met. No skipping phases.

### State Survival
File-based state survives:
- Context compaction
- Session end
- Machine switch

### Stall Detection
If stuck on same topic for 3+ turns, invokes The Challenger.

---

## Integration

### With Obra Superpowers
- White Room → `superpowers:writing-plans` → `superpowers:executing-plans`
- Export generates Obra-compatible plan files

### With Beads
- Export generates `beads-import.json`
- Import with `bd import docs/white-room/exports/beads-import.json`

### With Ralph Loops
- Export generates `prd.json` for autonomous building

---

## Why "White Room"?

In aerospace, a "white room" is a contamination-free environment where spacecraft are assembled. Nothing unexamined enters.

The White Room for software is where ideas are thoroughly examined before implementation begins. No shortcuts. No assumptions. No "we'll figure it out later."

---

## Success Criteria

The White Room is working when:
1. ✓ Stranger Test passes (>85% confidence)
2. ✓ All adversarial personas satisfied
3. ✓ No unresolved blockers
4. ✓ Task breakdown is actionable
5. ✓ Someone else can build it without questions

---

**Version:** 1.0
**Author:** Built with Claude
**License:** MIT