wip

docs/WIZARD_AUTO_SKIP_SUMMARY.md

@@ -0,0 +1,72 @@
+# 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)*