Solo troubleshoot

Troubleshoot Solo

Find root cause with smallest evidence set. Separate configuration, trust, lifecycle, listener readiness, and application health before changing anything.

Workflow

1. Restate symptom and expected state.
   • Identify project, process, action, last known good state, and recent config/profile/shell change.
   • Ask only when target or desired state cannot be inferred safely.
2. Establish Solo scope.
   • Call whoami, list_projects, and select_project as needed.
   • Call get_project_status, then get_process_status for target.
3. Classify failure before reading broad logs.
   • Trust/config: untrusted variant, unsynced YAML, invalid working_dir, unknown command.
   • Launch/environment: unavailable profile, wrong WSL root, missing PATH, version-manager function only.
   • Runtime: failed/exited process, crash-loop exhaustion, watcher-triggered restarts.
   • Readiness: running process without listener, wrong child/port, listener without healthy application.
   • Control plane: CLI/API discovery, token, version, app startup, or MCP scope issue.
4. Gather narrow evidence.
   • Use rendered output first; search exact error text.
   • Use raw output only for control sequences/redraw issues.
   • Inspect ports and subprocesses before scraping “ready” log messages.
   • Run solo doctor for CLI/app discovery failures.
5. State root cause and evidence.
   • Distinguish confirmed cause from remaining hypothesis.
   • If user asked only to diagnose, stop here.
6. Confirm repair authority.
   • Control only self and recorded Solo descendants self spawned.
   • Require exact user/runbook authority for parent, sibling, unrelated, YAML-backed shared process, or another agent's descendants.
   • Do not infer ownership from idle, stopped, failed, completed, or handed-off state.
7. Apply smallest authorized repair.
   • Require UI trust review for untrusted command.
   • Sync YAML, refresh shell environment, fix profile/root/path, or restart only affected process as appropriate.
   • Preserve output until cause is understood.
   • Avoid delete/recreate when sync, path edit, or restart is sufficient.
8. Reproduce original check.
   • Confirm status transition.
   • Confirm listener with readiness tool when relevant.
   • Confirm application health separately when requested.
   • Report fixed cause, changed state, and unresolved risk.

Diagnostic order

Follow cheapest decisive checks:

1. Scope and process identity.
2. Trust and YAML sync state.
3. Saved command and working_dir.
4. Execution profile/environment availability.
5. Rendered startup output.
6. Crash restart exhaustion or file-watch churn.
7. Bound ports/child ownership.
8. Application-specific health.

Guardrails

• Never bypass trust, widen working directory outside repo, or enable broad auto-trust as quick fix.
• Never clear output before diagnosis.
• Never assume running means ready or listening means healthy.
• Never restart every project command when one target can be repaired.
• Never stop, restart, close, rename, input, clear, select, or deliver timer to process outside ownership without exact authority.
• Never edit shell startup files, solo.yml, or WSL mappings unless user requested repair.
• Never delete project/process state to cure stale UI without proving cheaper repair failed.
• Leave Git index, commits, pushes, publishing, deployment, and integration to root/operator.

Boundary

• Use project setup workflow for planned new configuration rather than failure recovery.
• Use process lifecycle workflow for straightforward requested start/stop/restart with no unexplained failure.
• Use service observation workflow for read-only status/URL/log report with no diagnosis request.

Reference

Read diagnostic reference before diagnosing trust, YAML sync, shell/version manager, execution profile/WSL, crash-loop, readiness, output retention, or CLI/API failures.