# Wizard Auto-Skip Detection - Implementation Guide

## Problem
iRacing wizard auto-skips steps 8-10 when defaults are acceptable, causing Step 8→11 jump that breaks automation validation.

## Solution Architecture

### 3 Core Methods (Infrastructure Layer Only)

**1. Detection** - `detectActualWizardPage(): Promise<number | null>`
```typescript
// Check which #set-* container exists
const mapping = {
  '#set-cars': 8, '#set-track': 11, '#set-time-limit': 7, 
  // ... other steps
};
// Return step number of first found container
```

**2. Synchronization** - `synchronizeStepCounter(expected: number): Promise<StepSyncResult>`
```typescript
const actual = await this.detectActualWizardPage();
if (actual > expected) {
  return { 
    skippedSteps: [expected...actual-1],  // e.g., [8,9,10]
    actualStep: actual 
  };
}
```

**3. Execution Integration** - Modify `executeStep()`
```typescript
async executeStep(stepId: StepId, config) {
  if (this.isRealMode()) {
    const sync = await this.synchronizeStepCounter(step);
    if (sync.skippedSteps.length > 0) {
      sync.skippedSteps.forEach(s => this.handleSkippedStep(s)); // Log only
      return this.executeStepLogic(sync.actualStep, config);
    }
  }
  return this.executeStepLogic(step, config);
}
```

## TDD Plan (4 Phases)

1. **Unit**: Test detection returns correct step number
2. **Unit**: Test sync calculates skipped steps correctly
3. **Integration**: Test executeStep handles skips
4. **E2E**: Verify real wizard behavior

## Key Decisions

| Aspect | Choice | Why |
|--------|--------|-----|
| **Detection** | Container existence | Fast, reliable, already mapped |
| **Timing** | Pre-execution | Clean separation, testable |
| **Skip Handling** | Log + no-op | Wizard handled it, no validation needed |
| **Layer** | Infrastructure only | Playwright-specific |

## Success Criteria
- ✅ Step 8→11 skip detected and handled
- ✅ All existing tests pass unchanged
- ✅ Detection <50ms overhead
- ✅ Clear logging for debugging

## Files Modified
- `PlaywrightAutomationAdapter.ts` (3 new methods + executeStep modification)
- Tests: 3 new test files (unit, integration, E2E)

---
*Complete design: [`WIZARD_AUTO_SKIP_DESIGN.md`](./WIZARD_AUTO_SKIP_DESIGN.md)*