Troubleshooting Router Skill

When to Use

Use this skill when the user reports a problem with a calculation or workflow. Route to the appropriate sub-skill based on the error type.

Routing Decision Tree

Step 1: Identify the error source

Ask the user or check the workflow status:

catgo_workflow_engine(action: "status", params: { workflow_id: "<wf_id>" })

If a specific task failed, get the error details:

catgo_workflow_engine(action: "get_result", params: {
  workflow_id: "<wf_id>",
  task_id: "<task_id>"
})

Step 2: Route based on error type

Error signature	Route to
VASP error messages (ZBRENT, BRMIX, EDDDAV, etc.)	troubleshooting/vasp_errors
SCF not converging, ionic relaxation oscillating	troubleshooting/convergence_issues
ORCA SCF/geometry convergence	troubleshooting/convergence_issues
CatGo engine errors (REMOTE_ERROR, stuck tasks)	troubleshooting/workflow_errors
HPC connection issues (SSH, SFTP)	troubleshooting/workflow_errors
POTCAR not found, missing files	troubleshooting/workflow_errors
Test/verify cluster config before submitting; POTCAR/pseudopotential/binary/module checks; job "completed" with no output	troubleshooting/cluster_config_test

Step 3: Gather diagnostics

Before routing, collect relevant information:

catgo_workflow_engine(action: "status", params: { workflow_id: "<wf_id>" })

For VASP/convergence issues, check the calculation output:

catgo_analyze(action: "convergence", params: {
  workflow_id: "<wf_id>",
  task_id: "<task_id>"
})

For system-level issues:

catgo_system(action: "status")

catgo_system(action: "errors")

Common Patterns

"My calculation failed"

1. Check workflow status to identify which task failed
2. Get the error message from the failed task
3. Route to the appropriate sub-skill

"My calculation is taking too long"

1. Check if it is still running or stuck
2. If running: check convergence progress -> convergence_issues
3. If stuck in READY/QUEUED: -> workflow_errors

"My results look wrong"

1. Check if the calculation converged
2. Check for warnings in the output
3. Often a convergence issue in disguise -> convergence_issues

"I cannot connect to the HPC"

Direct to workflow_errors for SSH/connection troubleshooting.

MCP Tool Examples

Full diagnostic sequence

1. Get workflow overview:

catgo_workflow_engine(action: "status", params: { workflow_id: "<wf_id>" })

2. Get failed task details:

catgo_workflow_engine(action: "get_result", params: {
  workflow_id: "<wf_id>",
  task_id: "<failed_task_id>"
})

3. Check convergence if applicable:

catgo_analyze(action: "convergence", params: {
  workflow_id: "<wf_id>",
  task_id: "<task_id>"
})

4. Check system health:

catgo_system(action: "status")

5. Based on findings, route to the appropriate sub-skill and apply fixes.

Quick retry after fixing parameters

catgo_workflow_engine(action: "modify_params", params: {
  workflow_id: "<wf_id>",
  task_id: "<task_id>",
  params: { "ALGO": "All", "NELM": 200 }
})

catgo_workflow_engine(action: "retry", params: {
  workflow_id: "<wf_id>",
  task_id: "<task_id>"
})

Key Principle

Always diagnose before prescribing. Do not blindly suggest parameter changes without first understanding what went wrong. Use the diagnostic tools (status, get_result, convergence analysis) to identify the root cause, then apply targeted fixes.