dss/.dss/DSS_SELF_DEBUG_METHODOLOGY.md

DSS Self-Debugging Methodology

Purpose: Use DSS to debug DSS using its own infrastructure
Principle: Self-referential debugging - the system observes itself
Date: 2025-12-05

---

Overview: Self-Referential Debugging Architecture

DSS Running (Dashboard/Admin UI)
    ↓
Audit Logger (Records all actions)
    ├─ User interactions
    ├─ API calls
    ├─ Permission checks
    ├─ State changes
    └─ Errors (with stack traces)
    ↓
Workflow Persistence (Snapshots)
    ├─ Current page state
    ├─ User/team context
    ├─ Component states
    └─ Figma connection status
    ↓
Error Recovery (Crash Detection)
    ├─ Recovery points
    ├─ Error categorization
    ├─ Stack traces
    └─ Retry strategies
    ↓
Browser Console (Raw Logs)
    ├─ JavaScript errors
    ├─ Network requests
    ├─ Component lifecycle
    └─ Performance metrics
    ↓
Debug Inspector (NEW - To Be Built)
    ├─ View audit logs
    ├─ View state snapshots
    ├─ View crash reports
    ├─ Analyze performance
    └─ Replay state

---

Layer 1: Audit Logger Inspection

Purpose: See what actions were taken and in what order

Location: admin-ui/js/core/audit-logger.js

Available Data:

// Each log entry contains:
{
  timestamp: 1733425200000,
  sessionId: "session-1733425200000-abc123",
  action: "page_change",
  category: "navigation",
  level: "info",
  details: {
    from: "/",
    to: "/settings",
    user: "admin@example.com",
    timestamp: 1733425200000
  },
  redacted: false
}

Inspection Query:

// Access from browser console:
window.__DSS_DEBUG.auditLogger.getLogs({
  action: 'api_call',
  level: 'error',
  timeRange: { start: Date.now() - 3600000, end: Date.now() }
})

What to Look For:

1. ✅ Sequence of actions leading to error
2. ✅ Permission checks that failed
3. ✅ API calls and their responses
4. ✅ State mutations and side effects
5. ✅ Error patterns (repeated errors)

---

Layer 2: Workflow Persistence Inspection

Purpose: See what state the application was in at different points

Location: admin-ui/js/core/workflow-persistence.js

Available Data:

// Each snapshot contains:
{
  id: "snapshot-1",
  timestamp: 1733425200000,
  label: "before-settings-change",
  state: {
    currentPage: "/settings",
    user: { id: "123", role: "TEAM_LEAD" },
    team: { id: "team-1", name: "Design" },
    figmaConnected: true,
    selectedComponent: "Button",
    settings: { theme: "dark", ... }
  }
}

Inspection Query:

// From browser console:
window.__DSS_DEBUG.workflowPersistence.getSnapshots()
// Shows all saved snapshots

// Restore to specific point:
window.__DSS_DEBUG.workflowPersistence.restoreSnapshot("snapshot-id")

What to Look For:

1. ✅ State before error occurred
2. ✅ Configuration values at time of issue
3. ✅ User permissions and roles
4. ✅ Component selection states
5. ✅ Connection status (Figma, APIs, etc.)

---

Layer 3: Error Recovery Inspection

Purpose: See what crashed and how to recover

Location: admin-ui/js/core/error-recovery.js

Available Data:

// Crash detection:
{
  crashDetected: true,
  lastActivityTime: 1733425200000,
  timeSinceCrash: 45000, // ms
  errorCategory: "PERMISSION_DENIED",
  error: {
    type: "Error",
    message: "User does not have permission to access settings",
    stack: "..."
  },
  recoveryPoints: [
    { id: "rp-1", timestamp: 1733425100000, label: "before-api-call" },
    { id: "rp-2", timestamp: 1733425150000, label: "before-state-update" }
  ]
}

Inspection Query:

// From browser console:
window.__DSS_DEBUG.errorRecovery.getCrashReport()
// Returns full analysis

// Recover to specific point:
window.__DSS_DEBUG.errorRecovery.recover("rp-2")

What to Look For:

1. ✅ Error type and message
2. ✅ When crash occurred
3. ✅ Available recovery points
4. ✅ Stack trace for root cause
5. ✅ Retry strategies

---

Layer 4: Browser Console Analysis

Purpose: Raw JavaScript and network debugging

JavaScript Errors

// In browser console (F12):
// Look for:
// - Red error messages (uncaught exceptions)
// - Stack traces with file names and line numbers
// - Related warnings (yellow)

// Search by timestamp or error pattern:
// Watch Network tab for failed requests

Network Requests

Network Tab (F12 → Network):
- Filter by: XHR/Fetch
- Look for: 4xx/5xx responses
- Check: Request headers, response payload
- Analyze: Response time and size

Performance

Performance Tab (F12 → Performance):
- Record user interaction
- Look for: Long tasks (red)
- Check: JavaScript execution time
- Analyze: Paint times and layout shifts

---

Layer 5: Debug Inspector (To Be Built)

Purpose: Unified debugging dashboard within DSS

Proposed Interface:

┌─────────────────────────────────────────────┐
│  DSS Debug Inspector (Ctrl+Alt+D)           │
├─────────────────────────────────────────────┤
│                                             │
│  📊 Dashboard                               │
│  ├─ Current State Snapshot                  │
│  ├─ Recent Audit Logs (last 20)             │
│  ├─ Last Error (if any)                     │
│  └─ Recovery Points Available               │
│                                             │
│  🔍 Audit Logs                              │
│  ├─ Filter by action/level/time             │
│  ├─ Search by keyword                       │
│  ├─ View full details                       │
│  └─ Export as JSON                          │
│                                             │
│  💾 Snapshots                               │
│  ├─ List all saved snapshots                │
│  ├─ Compare two snapshots                   │
│  ├─ Restore to snapshot                     │
│  └─ Download snapshot                       │
│                                             │
│  ⚠️ Errors                                  │
│  ├─ Show crash report                       │
│  ├─ View error timeline                     │
│  ├─ Analyze error patterns                  │
│  └─ Retry from recovery point               │
│                                             │
│  ⚡ Performance                             │
│  ├─ Page load metrics                       │
│  ├─ API response times                      │
│  ├─ Component render times                  │
│  └─ Memory usage                            │
│                                             │
│  🔐 Permissions                             │
│  ├─ Current user role                       │
│  ├─ Available actions                       │
│  ├─ Denied actions (reason)                 │
│  └─ Team permissions                        │
│                                             │
└─────────────────────────────────────────────┘

---

Debugging Workflow: Step-by-Step

Scenario 1: Dashboard Not Loading

1. Check Browser Console (F12)

   • Any JavaScript errors?
   • Any failed network requests?

2. View Audit Logs

   window.__DSS_DEBUG.auditLogger.getStats()
   // Shows counts by category
   

3. Check Last Snapshot

   const snapshots = window.__DSS_DEBUG.workflowPersistence.getSnapshots();
   const last = snapshots[snapshots.length - 1];
   console.log(last.state); // See state before crash
   

4. Check Error Recovery

   window.__DSS_DEBUG.errorRecovery.getCrashReport()
   // Full analysis
   

5. Attempt Recovery

   const report = window.__DSS_DEBUG.errorRecovery.getCrashReport();
   if (report.recoveryPoints.length > 0) {
     window.__DSS_DEBUG.errorRecovery.recover(
       report.recoveryPoints[report.recoveryPoints.length - 1].id
     );
   }
   

---

Scenario 2: Permission Denied on Feature

1. Check Current User Role

   const snapshot = window.__DSS_DEBUG.workflowPersistence.getSnapshots().pop();
   console.log(snapshot.state.user.role);
   

2. View Permission Checks

   window.__DSS_DEBUG.auditLogger.getLogs({
     action: 'permission_check',
     details: { action: 'access_settings' }
   });
   

3. See Denied Reasons

   window.__DSS_DEBUG.auditLogger.getLogs({
     level: 'warning',
     category: 'permission'
   });
   

4. Compare Required vs Available

   • Check route-guards.js for permission mappings
   • See what role is required vs what user has

---

Scenario 3: API Call Failing

1. Find API Call in Audit Log

   window.__DSS_DEBUG.auditLogger.getLogs({
     action: 'api_call',
     timeRange: { 
       start: Date.now() - 60000,  // Last minute
       end: Date.now()
     }
   });
   

2. Check Network Tab

   • Filter by /api/*
   • Look for failed requests (red)
   • Check response for error message

3. View State Before Call

   // Find snapshot just before API error
   // Compare state to understand what was sent
   

4. Check Retry Logic

   window.__DSS_DEBUG.errorRecovery.getLogs()
   // See if retries occurred and outcomes
   

---

Methodology Principles

1. Layered Investigation

Start with highest-level (audit logs) and drill down (network, code)

2. Timeline Analysis

Look at events in sequence to understand causality

3. State Snapshots

Capture state before, during, and after issues

4. Permission Auditing

Check role-based access at each step

5. Error Categorization

Group errors by type to identify patterns

6. Recovery Strategy

Always attempt recovery from known good state

7. Non-Invasive

Debugging tools should not modify system state

---

Browser DevTools Integration

Keyboard Shortcuts

F12                  - Open DevTools
Ctrl+Shift+K         - Open Console
Ctrl+Alt+D           - Open DSS Debug Inspector (when implemented)
Ctrl+Shift+J         - Open Console in new window
Ctrl+Shift+I         - Open DevTools (alternate)

Console Commands

// Get debug namespace
window.__DSS_DEBUG

// Quick audit log view
window.__DSS_DEBUG.auditLogger.getLogs().slice(-10)

// Quick state view
window.__DSS_DEBUG.workflowPersistence.getSnapshots().pop().state

// Quick error view
window.__DSS_DEBUG.errorRecovery.getCrashReport()

// Export for analysis
JSON.stringify(window.__DSS_DEBUG.auditLogger.getLogs(), null, 2)

---

Browser Log Reader Implementation

What We Can Capture

class BrowserLogReader {
  // Capture console logs
  captureConsoleLogs() {
    const logs = [];
    const originalLog = console.log;
    const originalError = console.error;
    
    console.log = (...args) => {
      logs.push({
        level: 'log',
        timestamp: Date.now(),
        message: args.join(' ')
      });
      originalLog(...args);
    };
    
    console.error = (...args) => {
      logs.push({
        level: 'error',
        timestamp: Date.now(),
        message: args.join(' '),
        stack: new Error().stack
      });
      originalError(...args);
    };
    
    return logs;
  }
  
  // Capture unhandled errors
  captureErrors() {
    const errors = [];
    window.addEventListener('error', (event) => {
      errors.push({
        type: 'error',
        message: event.message,
        file: event.filename,
        line: event.lineno,
        column: event.colno,
        stack: event.error?.stack
      });
    });
    
    window.addEventListener('unhandledrejection', (event) => {
      errors.push({
        type: 'unhandledRejection',
        reason: event.reason,
        stack: event.reason?.stack
      });
    });
    
    return errors;
  }
  
  // Export for analysis
  exportLogs() {
    return {
      consoleLogs: this.logs,
      errors: this.errors,
      timestamp: new Date().toISOString(),
      url: window.location.href
    };
  }
}

---

Next Steps: Build Debug Inspector

Phase 1: Console Commands (Week 1)

• Expose audit logger to window.__DSS_DEBUG
• Expose workflow persistence to window.__DSS_DEBUG
• Expose error recovery to window.__DSS_DEBUG
• Create helper functions for common queries

Phase 2: Dashboard UI (Week 2)

• Create Debug Inspector component
• Build audit log viewer
• Build snapshot manager
• Build error analyzer

Phase 3: Advanced Features (Week 3)

• State comparison (before/after)
• Timeline visualization
• Performance profiling
• Log export/import

---

Usage Example

// 1. User reports: "Dashboard is slow"

// 2. In browser console:
const logs = window.__DSS_DEBUG.auditLogger.getLogs({
  category: 'api_call'
});

// 3. Find slow requests:
logs.forEach(log => {
  if (log.details.duration > 1000) {
    console.log(`Slow API: ${log.details.endpoint} (${log.details.duration}ms)`);
  }
});

// 4. Check state at time of slowness:
const snapshots = window.__DSS_DEBUG.workflowPersistence.getSnapshots();
const snapshotAtTime = snapshots.find(s => 
  s.timestamp > slowLog.timestamp - 1000 && 
  s.timestamp < slowLog.timestamp
);

// 5. Analyze:
console.log({
  slowEndpoint: slowLog.details.endpoint,
  stateAtTime: snapshotAtTime.state,
  duration: slowLog.details.duration
});

---

Benefits of This Approach

1. Self-Contained: No external tools needed
2. Historical: Full audit trail of everything
3. Stateful: Can see exact state at any point
4. Safe: No modifications to system
5. Complete: Captures all layers
6. Fast: Instant access to information

---

Conclusion

DSS now has all the infrastructure needed for comprehensive self-debugging:

• ✅ Audit logger tracks all actions
• ✅ Workflow persistence captures state
• ✅ Error recovery analyzes crashes
• ✅ Route guards log permissions

Next step: Build Debug Inspector UI to visualize this data.