dss/.dss/WORKFLOWS/README.md

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

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

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

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

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

# 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

# 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

# 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.