Start with read-only evidence. Do not restart services, repair state, remove data, or change project scope until a professional administrator has reviewed the diagnosis and rollback path.
1. Capture general diagnostics
From the release checkout:
python -m src.cli doctor --json
Keep the output with the CodeGraph revision, time, environment, project, and user-visible symptom. Redact tokens, credentials, customer source, and personal data before sharing it.
2. Narrow the failing surface
python -m src.cli doctor config
python -m src.cli doctor project --help
python -m src.cli doctor cpg --help
python -m src.cli doctor openviking --help
python -m src.cli doctor temporal --help
Run the relevant subcommand with its documented project selector. When the project identity is available, use the project interface and its recorded storage binding.
3. Inspect a local development stack
For an explicitly local source environment:
python scripts/run_app_stack.py status --local --with-mcp
python scripts/run_app_stack.py logs --local --with-mcp
These commands are not the customer service-manager procedure. On a customer Ubuntu deployment,
use the systemctl, Compose, and readiness commands from the installation guide.
4. Review a repair plan
Some doctor surfaces support safe repairs. Always inspect the plan first:
python -m src.cli doctor config --repair --dry-run
Apply a repair when its target, backup, expected postcondition, and rollback have been approved. Use the recorded change and postcondition to confirm that the mutation succeeded.
Symptom routing
| Symptom | First evidence |
|---|---|
| Startup/config rejection | doctor config, service status, readiness output |
| Project not visible | projects list, projects resolve-scope, access identity |
| Stale or missing graph | import job, doctor project, doctor cpg |
| MCP unavailable | API/MCP readiness, /status, project binding |
| Context degraded | doctor openviking, freshness warning, sync state |
| Workflow delayed | doctor temporal, task/session identifier |
Do not clear persistent volumes, kill broad process groups, disable TLS verification, or print environment secrets as a first-line diagnostic.
Escalation packet
Provide support with:
- exact symptom and expected behavior;
- timestamp, environment, release ref, and resolved commit;
- tenant/group/project and session or job identifier;
- sanitized doctor and readiness output;
- steps already taken and whether any state changed.
Contract sources
src/cli/governance_suite/doctor_commands.py— diagnostic parser;src/cli/doctor_commands.py— diagnostic execution routing;scripts/run_app_stack.py— local stack lifecycle;scripts/run_app_stack_readiness.py— shared runtime readiness.
See also: Installation · Configuration