Preserve the complete logs before classifying anything.
Compact CI summaries frequently omit the first useful error. Keep the full failed output and a successful comparison run long enough to reproduce the analysis.
Capture full Editor and job output
Retain the complete Unity log, surrounding CI step output, exit code, job/attempt identifier, timestamps, and non-secret platform metadata.
Choose an accepted last-green
Prefer the nearest successful run with the same branch role and build contract, not merely the most recent green job on any target.
Redact deterministically
Remove secrets before analysis with versioned rules. Preserve line structure and stable placeholders so evidence locations remain reviewable.
Decide whether suppression is defensible.
Errors present in a successful run can be useful noise controls only when the two runs are meaningfully comparable.
Compare build context
Check Unity version, target, scripting backend, build method, platform tooling, runner image, dependency-lock state, and relevant job configuration.
Report mismatches before diagnosis
A material context change should lower confidence or stop last-green suppression. Keep the mismatch in the output rather than silently normalizing it away.
Normalize only volatile tokens
Timestamps, durations, process IDs, temporary paths, ports, hashes, and runner-specific prefixes may be normalized by explicit rule; semantic error content should remain.
Find the first new error chain, not the loudest final line.
Cascading Unity failures often end with generic build-failed messages. Work forward from the earliest materially new chain that survives comparison.
Group continuations
Keep stack traces, nested exceptions, compiler continuations, and multi-line package or platform-tool errors attached to their initiating line.
Suppress shared successful-run noise
Mark exact or rules-equivalent chains present in the comparable last-green log, but preserve counts and links so a reviewer can challenge the suppression.
Fingerprint the surviving chain
Hash or label the normalized chain with the rule version. Recurrence should be stable; changes to normalization must produce a new version.
Return one bounded branch and allow unknown.
The useful output is the next discriminating check, not a confident paragraph assembled from weak correlations.
Use a small failure taxonomy
Begin with compiler, package resolution, import/serialization, platform toolchain, licensing, cache, test, infrastructure, and unknown. Each class needs an explicit rule.
Correlate changes conservatively
Changed paths can support a branch when a rule connects them to the observed chain. File proximity or commit timing alone is not root-cause evidence.
Name one discriminating action
Suggest a bounded check such as isolated package resolution, a clean build, or local batch-mode reproduction, with the source lines and rule that justify it.
Inspect the underlying documentation.
This guide is XeSoft's evaluation framework, not a substitute for the source documentation. Links below go to the primary publisher.
Unity recommends full-log inspection, comparison with a previous successful build, clean builds, and local batch-mode reproduction as diagnostic branches.
UnityBuildSummary scripting API ↗Structured build result, warning/error, duration, platform, and timestamp context.