dss/.dss/DEBUG_QUICKSTART.md

# DSS Debug Inspector - Quick Start Guide

## Getting Started (2 minutes)

### 1. Open Browser DevTools
Press **F12** in your browser on the DSS dashboard

### 2. Go to Console Tab
Click the "Console" tab at the top

### 3. Access Debug Inspector
Type in the console:
```javascript
window.__DSS_DEBUG.help()
```

This shows you all available commands.

---

## Common Debugging Tasks

### "My Dashboard Won't Load"

1. In console:
```javascript
window.__DSS_DEBUG.printDiagnosis()
```

2. Look for:
   - Any errors in "Recent Activity"
   - "Crash Detected" section
   - Available recovery points

3. If crash detected, recover:
```javascript
const report = window.__DSS_DEBUG.errorRecovery.getCrashReport();
if (report.recoveryPoints.length > 0) {
  window.__DSS_DEBUG.errorRecovery.recover(
    report.recoveryPoints[report.recoveryPoints.length - 1].id
  );
}
```

---

### "The Dashboard is Slow"

1. In console:
```javascript
const metrics = window.__DSS_DEBUG.getPerformanceMetrics();
console.table(metrics.slowCallDetails);
```

2. Look for:
   - Which endpoints are slow (> 1000ms)
   - How many API calls are happening
   - Any failed calls

3. Example output:
```
┌─────────────────────────────────────────┐
│  endpoint    │ method │ duration │ status │
├─────────────────────────────────────────┤
│ /api/figma   │ GET    │ 2500ms   │ 200    │
│ /api/config  │ GET    │ 1200ms   │ 200    │
└─────────────────────────────────────────┘
```

---

### "I Got an Error"

1. Check the error:
```javascript
const crashReport = window.__DSS_DEBUG.errorRecovery.getCrashReport();
console.log(crashReport.error);
```

2. See what state you were in:
```javascript
const snapshots = window.__DSS_DEBUG.workflowPersistence.getSnapshots();
const lastSnapshot = snapshots[snapshots.length - 1];
console.log(lastSnapshot.state);
```

3. Find what triggered it:
```javascript
const logs = window.__DSS_DEBUG.findLogs({ level: 'error' });
console.table(logs.slice(-5));
```

---

### "Feature X Isn't Working"

1. Trace the action:
```javascript
const logs = window.__DSS_DEBUG.findLogs('feature-name');
console.table(logs);
```

2. Check permissions:
```javascript
const logs = window.__DSS_DEBUG.findLogs({ 
  action: 'permission_check',
  level: 'warning'
});
console.table(logs);
```

3. Check current user role:
```javascript
const snapshot = window.__DSS_DEBUG.workflowPersistence.getSnapshots().pop();
console.log('User role:', snapshot.state.user.role);
```

---

### "I Need to Send Debug Info to Developer"

1. Export everything:
```javascript
const data = window.__DSS_DEBUG.exportDebugData();
```

This copies all debugging data to your clipboard as JSON.

2. Paste it in an email or issue report (it's JSON, safe to share)

---

## Available Commands Reference

### Diagnostics
```javascript
// Quick overview
window.__DSS_DEBUG.printDiagnosis()

// Detailed overview
window.__DSS_DEBUG.quickDiagnosis()

// Show help
window.__DSS_DEBUG.help()
```

### Search Logs
```javascript
// By pattern
window.__DSS_DEBUG.findLogs('api_call')

// By filters
window.__DSS_DEBUG.findLogs({
  action: 'api_call',
  level: 'error',
  timeRange: {
    start: Date.now() - 60000,  // Last minute
    end: Date.now()
  }
})
```

### Audit Logs
```javascript
// All logs
window.__DSS_DEBUG.auditLogger.getLogs()

// Filtered logs
window.__DSS_DEBUG.auditLogger.getLogs({
  action: 'page_change',
  level: 'info'
})

// Statistics
window.__DSS_DEBUG.auditLogger.getStats()
```

### Snapshots
```javascript
// All snapshots
window.__DSS_DEBUG.workflowPersistence.getSnapshots()

// Last snapshot
const snapshots = window.__DSS_DEBUG.workflowPersistence.getSnapshots();
snapshots[snapshots.length - 1]

// Restore to snapshot
window.__DSS_DEBUG.workflowPersistence.restoreSnapshot('snapshot-id')
```

### Error Recovery
```javascript
// Full crash report
window.__DSS_DEBUG.errorRecovery.getCrashReport()

// Recover
window.__DSS_DEBUG.errorRecovery.recover('recovery-point-id')
```

### Performance
```javascript
// All metrics
window.__DSS_DEBUG.getPerformanceMetrics()

// Export everything
window.__DSS_DEBUG.exportDebugData()
```

---

## Tips & Tricks

### 1. Clear Console, Run Diagnosis
```javascript
console.clear();
window.__DSS_DEBUG.printDiagnosis();
```

### 2. Watch for New Errors
```javascript
// Get current error count
const before = window.__DSS_DEBUG.findLogs({ level: 'error' }).length;

// Do something that might fail...

// Check if new errors
const after = window.__DSS_DEBUG.findLogs({ level: 'error' }).length;
console.log(`New errors: ${after - before}`);
```

### 3. Compare Before and After State
```javascript
const before = window.__DSS_DEBUG.workflowPersistence.getSnapshots()[0];
const after = window.__DSS_DEBUG.workflowPersistence.getSnapshots().pop();

console.log('Changes:');
console.log('Before:', before.state.currentPage);
console.log('After:', after.state.currentPage);
```

### 4. Monitor API Performance Over Time
```javascript
setInterval(() => {
  const metrics = window.__DSS_DEBUG.getPerformanceMetrics();
  console.log(`Avg API time: ${Math.round(metrics.averageResponseTime)}ms`);
}, 5000);
```

---

## What to Look For

### Signs of Problems
- ❌ Errors in "Recent Activity" section
- ❌ "Crash Detected" = true
- ❌ Failed API calls (status >= 400)
- ❌ Slow API calls (duration > 1000ms)
- ❌ Permission warnings (level: 'warning')

### Signs of Health
- ✅ No crashes detected
- ✅ Recent activity shows expected actions
- ✅ All API calls successful (status 200)
- ✅ Fast response times (< 500ms average)
- ✅ User role matches expected access level

---

## Next Steps

1. **Share Diagnosis**: If there's an issue, run:
   ```javascript
   window.__DSS_DEBUG.exportDebugData()
   ```
   And share the JSON output

2. **Report Pattern**: Include:
   - What you were doing
   - Console output from diagnosis
   - Performance metrics
   - Recent activity logs

3. **Check Documentation**: See full details in:
   - `.dss/DSS_SELF_DEBUG_METHODOLOGY.md`

---

## Getting Help

If you see an error or issue:

1. Run diagnostic
2. Look for error messages
3. Check recovery points
4. Export debug data
5. Share with development team

Everything the system recorded is available in the console.