WhysGuy — 5 Whys Root-Cause for GitLab Orbit

WhysGuy runs a 5 Whys root-cause analysis over GitLab Orbit's knowledge graph—proving every step with a real graph traversal and naming the exact line where the bug lives, instead of guessing.

Comment

Inspiration

Root-cause analysis is still one of the most manual and expensive parts of software development. When a test fails, a bug is reported, or a pipeline breaks, developers spend significant time retracing the same path: open a file, follow an import, jump to another definition, check references, and repeat, until they find the real cause. The symptom is almost never where the defect actually lives.

Existing AI assistants make this worse in a subtle way: they produce a plausible explanation but cannot prove the dependency path they followed. You get a confident-sounding answer with no evidence, and the reasoning evaporates the moment the bug is fixed, so the next person hits the same wall.

GitLab Orbit changes the economics. The codebase is already a queryable knowledge graph. We wanted an agent that reasons over that graph instead of guessing.

What it does

WhysGuy is a custom GitLab Duo Agent Platform agent that performs a structured 5 Whys root-cause investigation using GitLab Orbit as its reasoning engine.

Given a failing test, an exception, a file, a symbol, or a defect description, WhysGuy anchors the symptom in Orbit's graph and asks "why?" at each step. Every answer is backed by a real Orbit query. Instead of inventing a call chain, it follows real graph relationships (file containment, definition references, imports, and cross-file symbol resolution) and stops at the deepest definition whose own code contains the defect.

The result is a reproducible Root-Cause Report: the why-chain, every node cited with file and line, the exact Orbit queries it ran so a human can re-run them, and a specific recommended fix location. Instead of "Where do I even start looking?", the developer gets "Root cause identified in money.py line 19. Here is the exact dependency chain from the failing test to the defect."

How we built it

WhysGuy is a thin, legible layer on top of two GitLab primitives. First, a custom agent on the GitLab Duo Agent Platform (system prompt plus the Orbit Query Graph and Get Graph Schema tools), published to the AI Catalog as a public agent. Second, an Agent Skill (skills/whysguy-5whys/SKILL.md, following the Agent Skills specification) that encodes the 5 Whys method and ships paste-ready Orbit query-DSL recipes (traversal, neighbors, path_finding) so the agent composes valid graph queries on the first attempt.

GitLab Orbit is the reasoning substrate. We also built a small intentionally-buggy sample repo (demo/buggy-cart) with a verified, three-files-deep root cause to prove the traversal end to end: a failing checkout test whose true cause is a parse_money function that drops the cents, two imports away.

Challenges we ran into

Trusting the graph, not the model. The whole point is reproducibility, so the skill treats every "why" as a query result. If a query returns nothing, WhysGuy reports it rather than fabricating the missing edge.

A beta schema. Orbit is evolving, so the skill instructs the agent to read the live graph schema first and prefer the neighbors query, which does not require knowing edge-type names, with multi-node traversals as a verified optimization.

Keeping it legible. We made WhysGuy a thin, readable layer on top of a custom agent plus a skill, so judges and other developers can read exactly how it works.

Accomplishments that we're proud of

WhysGuy produces a fully evidence-linked root-cause investigation where every hop is a real Orbit query, not a guess. On the demo it traces from a failing test, through two intermediate files, to the exact defective line, and recommends the one-line fix. It is published and public in the AI Catalog, installable by any team, and the entire method lives in a readable open-source skill. It is honest about its limits: five is the discipline, not a hard cap, and it reports remaining uncertainty instead of padding the chain.

What we learned

Orbit is far more than code search. Reframing a classic investigative method, the 5 Whys, as graph traversal turns LLM debugging from "the AI guessed" into "the AI showed its work." The graph is what makes the reasoning auditable.

What's next for WhysGuy

Extend the why-chain into the merge request and pipeline that introduced the root-cause definition, using Orbit Remote. Auto-file the Root-Cause Report as a GitLab issue with the why-chain pre-filled. And add a regression guard that stores solved why-chains so WhysGuy recognizes a recurring root cause on sight.

Built With

  • agent-skills
  • gitlab-duo-agent-platform
  • gitlab-orbit
  • glab
  • knowledge-graph
  • orbit-query-dsl
  • python
Share this project:

Updates