This manual teaches teams how to troubleshoot from the symptom layer instead of guessing at the wrong cause.
Use it when telemetry is blank, attribution is wrong, degraded output is hidden, or runtime behavior looks inconsistent across surfaces.
Chat works, telemetry is blank
Start at the aggregation endpoint and verify metadata survives into overview and runtime-detail outputs.
source / module / scene are wrong
Start at the execution path and inspect later merges that overwrite the original context.
Fallback looks healthy
Start at the rendering layer and verify degraded fields are not being flattened away.
Different surfaces behave differently
Return to role ownership and confirm which host module actually owns each surface and endpoint.
Troubleshooting order: 1. Define the symptom precisely 2. Identify which layer exposes the symptom 3. Export the current exact path and ownership 4. Verify metadata continuity end to end 5. Verify normalized response shape 6. Verify operator-facing aggregation and rendering 7. Only then patch the broken layer
Observation Manual
Use observation first to confirm the signal is real and to see where concentration is happening.
Optimization Assistant Manual
Use it after troubleshooting isolates a fixable pattern that should be turned into structured optimization work.
Contract Reference
Use it when debugging exact request, response, degraded, or structured error semantics.