276ed71f31
Migrated from design-system-swarm with fresh git history.
Old project history preserved in /home/overbits/apps/design-system-swarm
Core components:
- MCP Server (Python FastAPI with mcp 1.23.1)
- Claude Plugin (agents, commands, skills, strategies, hooks, core)
- DSS Backend (dss-mvp1 - token translation, Figma sync)
- Admin UI (Node.js/React)
- Server (Node.js/Express)
- Storybook integration (dss-mvp1/.storybook)
Self-contained configuration:
- All paths relative or use DSS_BASE_PATH=/home/overbits/dss
- PYTHONPATH configured for dss-mvp1 and dss-claude-plugin
- .env file with all configuration
- Claude plugin uses ${CLAUDE_PLUGIN_ROOT} for portability
Migration completed: $(date)
🤖 Clean migration with full functionality preserved
263 lines
6.9 KiB
Markdown
263 lines
6.9 KiB
Markdown
# 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.
|