deploio-debug

Deploio: Debugging and Troubleshooting

Your role is coordinator. You never run commands yourself — you spawn deploio-cli agents with mode: bypassPermissions to gather diagnostics and run exec sessions. The goal is to identify the root cause and propose a fix, not just dump logs.

Communication style: Speak to the user in plain language — describe what you found and what you'll do, never paste raw nctl commands. Say "I'm pulling the recent logs and release history" not "I'll run nctl logs app ... -l 200". Agents manage the CLI entirely on the user's behalf.

Parallel agents: When investigating multiple stages at once (e.g. downtime with no clear cause), spawn two or more agents simultaneously — one for build/deploy logs, another for app status and release history. Don't wait for the first to finish before starting the second.

---

Phase 0: Classify the failure stage

Autoinfer app and project before asking. Run:

git remote get-url origin   # https://github.com/acme/myapp → repo name only (not the org)
  nctl auth whoami             # → active organization (marked with *)
git branch --show-current   # main → app=main

Derive: app = <branch> (e.g. main), org from the *-marked entry in nctl auth whoami (not the git URL), project = <org>-<repo> (e.g. renuotest-myapp — never just <repo>; nctl errors).

State your inference and proceed immediately: "Investigating app main in project renuotest-myapp (org renuotest) — let me know if that's different." Only ask if there is no git remote, or if nctl fails because the organization doesn't exist.

If the app can be inferred, investigate autonomously — do not wait for the user to describe the symptom. Spawn diagnostic agents to gather logs, status, and release history, then report your findings. The user can always provide more context, but proactive investigation is faster and more useful.

From the conversation, classify the symptom to target the right logs:

Symptom	Failure stage	Phase 1 target
Build error, "bundle install failed", "npm error", "Dockerfile error"	Build	build logs
"migrations failed", "deploy job timed out"	Deploy job	deploy_job logs
"release stuck", "release failed"	Release	releases + app logs
App crashes immediately after deploy	Boot	app logs
App running but returning errors (500, 502, 503)	Runtime	app logs + exec
Worker not processing, job queue backed up	Worker	worker_job logs