Hello-QM/catgo-LRG / server/catgo/workflow/skills/troubleshooting
troubleshooting-router
VerifiedRoutes troubleshooting requests to vasp_errors, convergence_issues, or workflow_errors sub-skills based on the type of problem.
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"
- Check workflow status to identify which task failed
- Get the error message from the failed task
- Route to the appropriate sub-skill
"My calculation is taking too long"
- Check if it is still running or stuck
- If running: check convergence progress ->
convergence_issues - If stuck in READY/QUEUED: ->
workflow_errors
"My results look wrong"
- Check if the calculation converged
- Check for warnings in the output
- 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
- Get workflow overview:
catgo_workflow_engine(action: "status", params: { workflow_id: "<wf_id>" })
- Get failed task details:
catgo_workflow_engine(action: "get_result", params: {
workflow_id: "<wf_id>",
task_id: "<failed_task_id>"
})
- Check convergence if applicable:
catgo_analyze(action: "convergence", params: {
workflow_id: "<wf_id>",
task_id: "<task_id>"
})
- Check system health:
catgo_system(action: "status")
- 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |