Debug Command

synapse-plugin-helper:debug Command Workflow

Codex Adaptation

• Treat the user request or explicitly supplied text as the command arguments.
• Use the available Codex file, search, terminal, and clarification capabilities that match the workflow.
• Do not depend on Claude-only slash command variables or tool names.

Debug Synapse Plugin

Diagnose and resolve common issues with Synapse plugins.

Arguments: the user request or explicit arguments

Workflow

Step 1: Identify Problem

If error message provided in the user request or explicit arguments:

• Parse the error type and message
• Identify likely cause

If no specific error:

• Ask user to describe the issue
• Run diagnostic checks

Step 2: Run Diagnostic Checks

Execute these checks in order:

1. Config Validation

# Check config.yaml or synapse.yaml exists and is valid
CONFIG_FILE=config.yaml
if [ -f synapse.yaml ]; then CONFIG_FILE=synapse.yaml; fi
cat "$CONFIG_FILE"

Verify:

• name and code fields present
• actions section defined
• Entrypoints use correct format (module:ClassName or module.function)

2. Entrypoint Verification

# Check entrypoint files exist
python -c "from [module] import [class]"

Verify:

• Module file exists
• Class/function is importable
• No syntax errors

3. Dependency Check

# Verify requirements installed
pip check
pip list | grep -E "synapse|pydantic|ray"

Verify:

• synapse-sdk installed
• pydantic installed
• All requirements.txt packages installed

4. Parameter Schema Check

# Validate Pydantic models
python -c "from [module] import [ParamsClass]; print([ParamsClass].model_json_schema())"

Step 3: Common Issues & Solutions

Step 4: Detailed Analysis

If automated checks don't find issue:

1. Use the troubleshooter agent for deeper analysis
2. Check logs with /synapse-plugin:logs
3. Review recent changes in config.yaml or action code

Step 5: Provide Solution

After identifying the issue:

1. Explain the root cause
2. Provide specific fix instructions
3. Show corrected code if applicable
4. Suggest prevention measures

Quick Fixes

Fix import errors:

export PYTHONPATH="${PYTHONPATH}:$(pwd)"

Fix missing synapse-sdk:

pip install synapse-sdk

Fix config.yaml formatting:

python -c "import yaml; yaml.safe_load(open('config.yaml'))"

Sync config with code:

synapse plugin update-config

Invoke Troubleshooter Agent

For complex issues, the troubleshooter agent provides:

• Deep error log analysis
• Pattern matching against known issues
• Web search for similar problems
• Step-by-step resolution guidance