Skip to content

Hello-QM/catgo-LRG / server/catgo/workflow/skills/troubleshooting

troubleshooting-router

Verified

Routes 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 signatureRoute to
VASP error messages (ZBRENT, BRMIX, EDDDAV, etc.)troubleshooting/vasp_errors
SCF not converging, ionic relaxation oscillatingtroubleshooting/convergence_issues
ORCA SCF/geometry convergencetroubleshooting/convergence_issues
CatGo engine errors (REMOTE_ERROR, stuck tasks)troubleshooting/workflow_errors
HPC connection issues (SSH, SFTP)troubleshooting/workflow_errors
POTCAR not found, missing filestroubleshooting/workflow_errors
Test/verify cluster config before submitting; POTCAR/pseudopotential/binary/module checks; job "completed" with no outputtroubleshooting/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>" })
  1. Get failed task details:
catgo_workflow_engine(action: "get_result", params: {
  workflow_id: "<wf_id>",
  task_id: "<failed_task_id>"
})
  1. Check convergence if applicable:
catgo_analyze(action: "convergence", params: {
  workflow_id: "<wf_id>",
  task_id: "<task_id>"
})
  1. Check system health:
catgo_system(action: "status")
  1. 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.

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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall