# DSS Debug Workflows

**Purpose**: Step-by-step procedures for common debugging tasks in Design System Swarm

**How to Use**: Each workflow is a standalone markdown document with:
- Clear prerequisites
- Step-by-step instructions with console commands
- Expected results for each step
- Troubleshooting guidance
- Success criteria

---

## Available Workflows

### [01 - Capture Browser Logs](01-capture-browser-logs.md)
**Purpose**: Capture and retrieve all browser-side logs from DSS dashboard

**When to Use**:
- User reports dashboard not loading
- JavaScript errors in browser
- Network request failures
- Performance issues

**Estimated Time**: 2-5 minutes

**Key Steps**:
1. Open dashboard and DevTools
2. Verify browser logger loaded
3. Get diagnostic summary
4. Retrieve specific log types
5. Export logs for analysis

---

### [02 - Diagnose Errors](02-diagnose-errors.md)
**Purpose**: Systematically diagnose and resolve errors in DSS dashboard and API

**When to Use**:
- Dashboard displays error messages
- API requests failing
- Server health check shows degraded status
- User reports functionality not working

**Estimated Time**: 10-30 minutes

**Key Steps**:
1. Identify error scope (browser/API/database/system)
2. Diagnose browser-side errors
3. Diagnose API-side errors
4. Diagnose database errors
5. Diagnose system-wide issues
6. Verify fix

---

### [03 - Debug Performance](03-debug-performance.md)
**Purpose**: Diagnose and resolve performance issues in DSS dashboard and API

**When to Use**:
- Dashboard loads slowly
- API requests taking too long
- Browser becomes unresponsive
- High memory usage warnings

**Estimated Time**: 15-45 minutes

**Key Steps**:
1. Gather performance baseline
2. Diagnose slow page load
3. Diagnose slow API requests
4. Diagnose memory leaks
5. Diagnose CPU bottlenecks
6. Server-side performance check

---

### [04 - Workflow Debugging](04-workflow-debugging.md)
**Purpose**: Debug the workflow system itself and MCP tool integration

**When to Use**:
- Workflow execution fails
- MCP tools not responding
- API endpoints returning errors
- Communication between layers broken

**Estimated Time**: 10-20 minutes

**Key Steps**:
1. Verify all services running
2. Test each layer independently
3. Test data flow end-to-end
4. Debug common workflow issues
5. Verify workflow execution
6. Check persistence (supervisord)

---

## Quick Reference

### Access from Command Line
```bash
# View workflow list
ls -1 /home/overbits/dss/.dss/WORKFLOWS/*.md

# Read a workflow
cat /home/overbits/dss/.dss/WORKFLOWS/01-capture-browser-logs.md

# Quick hook for browser logs
/home/overbits/dss/.dss/GET_BROWSER_LOGS.sh
```

### Access from API
```bash
# List workflows
curl http://localhost:3456/api/debug/workflows

# Execute workflow (when implemented)
curl -X POST http://localhost:3456/api/debug/workflows/01-capture-browser-logs
```

### Access from MCP (Claude Code)
```
Use tool: dss_list_workflows
Use tool: dss_run_workflow with workflow_name="01-capture-browser-logs"
```

---

## Workflow Categories

### User-Facing Issues
- **01 - Capture Browser Logs**: First step for any dashboard issue
- **02 - Diagnose Errors**: When specific errors occur

### Performance Issues
- **03 - Debug Performance**: Slow loading, high memory, CPU bottlenecks

### System Issues
- **04 - Workflow Debugging**: When the debug tools themselves fail

---

## Architecture Context

These workflows operate within the 3-layer debug architecture:

```
┌──────────────────────────────────────────┐
│ Layer 1: Browser (JavaScript)            │
│  - browser-logger.js captures logs       │
│  - window.__DSS_BROWSER_LOGS API         │
└──────────────────────────────────────────┘
                   ↓
┌──────────────────────────────────────────┐
│ Layer 2: API Server (FastAPI)            │
│  - /api/browser-logs endpoints           │
│  - /api/debug/* endpoints                │
└──────────────────────────────────────────┘
                   ↓
┌──────────────────────────────────────────┐
│ Layer 3: MCP Server (Python/MCP)         │
│  - dss_get_browser_diagnostic            │
│  - dss_get_browser_errors                │
│  - dss_run_workflow                      │
└──────────────────────────────────────────┘
```

See `.dss/MCP_DEBUG_TOOLS_ARCHITECTURE.md` for complete architecture details.

---

## Development Guide

### Creating New Workflows

1. **Choose Number**: Next sequential number (05, 06, etc.)
2. **Create File**: `.dss/WORKFLOWS/NN-workflow-name.md`
3. **Use Template**: See workflow 04 for template structure
4. **Include**:
   - Purpose and when to use
   - Prerequisites
   - Step-by-step instructions with commands
   - Expected results for each step
   - Troubleshooting guidance
   - Success criteria
   - Related documentation
5. **Test**: Run through workflow manually
6. **Refine**: Update based on actual experience
7. **Restart API**: To load new workflow in system

### Workflow Template Structure
```markdown
# Workflow NN: Title

**Purpose**: Brief description
**When to Use**: Scenarios
**Estimated Time**: X-Y minutes

---

## Prerequisites
- Required items

---

## Step-by-Step Procedure

### Step 1: Title
**Action**: Commands or actions
**Expected Result**: What should happen
**Troubleshooting**: If issues occur

---

## Success Criteria
- ✅ Checkpoints

---

## Related Documentation
- Links to related docs
```

---

## Maintenance

### Regular Testing
- Run workflow 04 monthly to verify system health
- Update workflows when architecture changes
- Add new workflows for recurring issues

### Update Triggers
- New debug tools added
- Architecture changes
- New common issues discovered
- User feedback on workflows

---

## Related Documentation

- `.dss/MCP_DEBUG_TOOLS_ARCHITECTURE.md` - Complete MCP integration architecture
- `.dss/BROWSER_LOG_CAPTURE_PROCEDURE.md` - Browser logger details
- `.dss/GET_BROWSER_LOGS.sh` - Quick reference hook
- `.dss/DSS_DIAGNOSTIC_REPORT_20251206.md` - Example diagnostic report
- `.dss/DEBUG_SESSION_SUMMARY.md` - Previous debug session

---

## Implementation Status

- ✅ **Workflow 01**: Capture Browser Logs - Complete
- ✅ **Workflow 02**: Diagnose Errors - Complete
- ✅ **Workflow 03**: Debug Performance - Complete
- ✅ **Workflow 04**: Workflow Debugging - Complete
- ⏳ **API Integration**: Endpoints need implementation
- ⏳ **MCP Integration**: Tools need implementation
- ⏳ **Supervisord**: Service configs need creation

See architecture doc for full implementation checklist.