The Consultant
Diagnosing and optimizing complex builds
Diagnose hard Bazel problems with evidence: query configured graphs, inspect actions, explain cache misses, read profiles, and connect symptoms to internals instead of inherited assumptions.
Hard Bazel problems rarely yield to another guessed flag. The consultant's role is to turn a report such as “the build is slow” or “the cache stopped working” into a bounded investigation: preserve the surprising state, keep competing explanations alive, and choose the smallest observation that can separate them.
5.1 Evidence-Led Investigation establishes that contract before introducing specialized tools. It asks what was actually held constant, what each hypothesis predicts, and how far the available evidence permits the diagnosis to reach. That discipline is the spine of the level. A query, profile, dump, or execution log is useful only when it answers a question inside that contract.
The Evidence Path
The first arc chooses the evidence surface. 5.2 Query separates declared, configured, and action graphs so that dependency, configuration, and execution questions do not blur together. 5.3 Graph Analysis then applies those views to bounded structural investigations and target-boundary decisions.
The second arc follows symptoms across time and repeated invocations. 5.4 Performance turns a representative workload into a matched measurement and a falsifiable intervention. 5.5 Observability widens the view carefully—from one structured invocation record to comparable cohorts—without mistaking a trend for its cause.
The third arc earns deeper evidence. 5.6 Debugging routes failures, regressions, and resource symptoms to narrow probes. 5.7 Cache & Execution compares reuse expectations with observed spawn differences, while 5.8 Sandboxing reconciles runtime access with the declared action boundary. 5.9 Skyframe is the final internal model for explaining retained computations and change propagation when supported graph and execution views no longer answer the bounded question.
Enter Through The Symptom
Read 5.1 Evidence-Led Investigation first even if you arrived with a familiar symptom. Then enter through the relevant section rather than collecting every artifact in order. Keep recommended branches for recurring work in that domain and extra branches for a specific question that the core path cannot answer. Finish with 5.10 Consultant Practicum, where a worked rebuild investigation and an unfamiliar CI dossier test whether the method transfers beyond a guided tool walkthrough.
Decide: A team wants to fix a slow or unexpectedly rebuilding target. What must the investigation establish before proposing a change?
Reveal
Name the graph layer where the symptom occurs, cite evidence that isolates the problem at that layer, and define a matched measurement that could confirm or reject the proposed improvement. If any of those is missing, the fix is still a hypothesis rather than an evidence-backed intervention.
A consultant investigation preserves provenance, keeps competing hypotheses falsifiable, chooses the least invasive discriminating evidence, and states a diagnosis no broader than that evidence. Level 5 applies that method to one bounded incident or controlled workload; operating shared services, fleet telemetry, capacity, and governance is the Level 6 responsibility.
Next: design the shared service boundary in 6.1 Shared Bazel Services.
