Best practices

Point it precisely

• Paste the run URL, not the repository name, when you already have the failed run open. It pins the investigation to that exact run instead of to whatever failed most recently, which matters on an active branch.
• Name the branch when several are red. Otherwise you may get a diagnosis for somebody else's failure and spend a minute confused before noticing.
• Investigate promptly. Run logs expire, and the value of the green-to-red diff decays as more commits land on the branch.

Make your CI legible

TraceCI reads what your pipeline produces. Pipelines that are easy for a person to diagnose are the ones it does well on, and the improvements are the same in both cases.

• Split setup from execution. A workflow with distinct Install, Lint and Test steps lets the failing step name do real work. A single step called build that does everything discards that signal entirely.
• Fail fast. A job that keeps going after the first real error buries the cause under thousands of consequence lines, which makes the log window harder to anchor correctly.
• Do not suppress output on failure. Redirecting test output to a file and printing only a summary removes the traceback, and the traceback is where the diagnosis starts.
• Keep runs green. The baseline is the last successful run. A branch that has not been green for thirty commits gives TraceCI a thirty-commit diff to search, and its accuracy falls accordingly.

Choose the model for the failure

• Free-tier models are fine for obvious failures — dependency conflicts, lint errors, config mistakes — where the log already contains the answer.
• Use a stronger model for subtle regressions. The decision that matters is whether to open a source file rather than guess from the traceback, and that is where smaller models most often go wrong.
• Validate the key before a real run. A model that cannot call tools fails silently, producing confident nonsense with no error anywhere.

Details are in models and keys.

Read results in the right order

1. The trace — how many tools, and were they aimed at anything the log named?
2. The evidence — does it establish the claim without the prose?
3. The root cause — does it name a file, a function and a value?
4. The confidence — and if it is below 5, find the inferred link.
5. The patch, last. It is the part you are least able to check on its own.

Fit it into how you already work

• Run it before you re-run the job. A green re-run destroys the evidence for a flaky test. Diagnose first, then re-run.
• Share the thread id, not a screenshot. The record contains the exact log window and diff the agent worked from, which is what a second reader needs.
• Treat it as triage, not as authority. Its job is to get you to the right file in thirty seconds instead of ten minutes. Confirming the fix is still yours.

Things not to do

• Do not apply a suggested patch without reading the evidence. A patch that resolves the symptom while the cause is elsewhere turns one red build into an intermittent one.
• Do not re-run TraceCI hoping for a better answer. If the first result was thin, the input was thin. Fix the input — a narrower branch, a more precise run, a less noisy log — instead.
• Do not use it as a log viewer. If you already know what broke, reading the log is faster.