name: syncause-debugger
description: Diagnose and fix bugs using runtime execution traces. Use when debugging errors, analyzing failures, or finding root causes in Python, Node.js, or Java applications.

Syncause Debugger

Use runtime traces to enhance bug fixing: collect runtime data with the SDK, then analyze with MCP tools.

Before fix, create a detailed plan to ensure no details are missed, always include 3 phases: Setup → Analyze → Teardown.

Phase 1: Setup

Pre-check

1. MCP Server: This skill depends on debug-mcp-server MCP server. If it is not present, STOP and request the user to install the MCP server (Installation Guide).
2. Authentication: If any MCP Tool returns a Unauthorized error, STOP and request the user to configure the API_KEY (Installation Guide).

Verify SDK NOT already installed by checking dependency files:
- Java: pom.xml or build.gradle
- Node.js: package.json
- Python: requirements.txt or pyproject.toml

WARNING: .syncause folder is NOT a reliable indicator.

Steps

1. Get credentials: get_project_id(projectPath) → returns projectId, apiKey, appName
2. WARNING: If tool not found or returns Unauthorized, STOP and follow Pre-check.
3. Install SDK: Follow language guide:
4. Java
5. Node.js
6. Python
7. Verify install: Re-read dependency file to confirm SDK added
8. Restart service: Prefer starting new instance on different port over killing process
9. Reproduce bug: Trigger the issue to generate trace data

Phase 2: Analyze & Fix

# Step 1: Find trace
search_debug_traces(query="<symptom>") → pick traceId

# Step 2: Get call tree
get_trace_insight(traceId) → find [ERROR] node

# Step 3: Inspect method
inspect_method_snapshot(traceId, methodName) → check args/return/logs

# Step 4 (optional): Compare traces
diff_trace_execution(baseTraceId) → compare fail vs success

Fix: Edit code based on findings, re-run to verify. After fix is confirmed, ALWAYS proceed to Phase 3: Teardown.

WARNING: No traces? → Return to Phase 1, ensure SDK active and bug reproduced.

Phase 3: Teardown

REQUIRED after debugging to restore performance.

1. Uninstall SDK: Follow language guide:
2. Java
3. Node.js
4. Python
5. Delete .syncause folder from project root