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:

window.__DSS_DEBUG.help()

This shows you all available commands.

---

Common Debugging Tasks

"My Dashboard Won't Load"

1. In console:

window.__DSS_DEBUG.printDiagnosis()

2. Look for:

   • Any errors in "Recent Activity"
   • "Crash Detected" section
   • Available recovery points

3. If crash detected, recover:

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:

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:

const crashReport = window.__DSS_DEBUG.errorRecovery.getCrashReport();
console.log(crashReport.error);

2. See what state you were in:

const snapshots = window.__DSS_DEBUG.workflowPersistence.getSnapshots();
const lastSnapshot = snapshots[snapshots.length - 1];
console.log(lastSnapshot.state);

3. Find what triggered it:

const logs = window.__DSS_DEBUG.findLogs({ level: 'error' });
console.table(logs.slice(-5));

---

"Feature X Isn't Working"

1. Trace the action:

const logs = window.__DSS_DEBUG.findLogs('feature-name');
console.table(logs);

2. Check permissions:

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

3. Check current user role:

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:

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

// Quick overview
window.__DSS_DEBUG.printDiagnosis()

// Detailed overview
window.__DSS_DEBUG.quickDiagnosis()

// Show help
window.__DSS_DEBUG.help()

Search Logs

// 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

// 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

// 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

// Full crash report
window.__DSS_DEBUG.errorRecovery.getCrashReport()

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

Performance

// All metrics
window.__DSS_DEBUG.getPerformanceMetrics()

// Export everything
window.__DSS_DEBUG.exportDebugData()

---

Tips & Tricks

1. Clear Console, Run Diagnosis

console.clear();
window.__DSS_DEBUG.printDiagnosis();

2. Watch for New Errors

// 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

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

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:

   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.