When the Signal Turns Red: Agent Troubleshooting Capability

The preceding four sections built a multi-layered feedback system: static analysis intercepts type issues in milliseconds, CI reports build and test results in minutes, observability tracks runtime behaviour over hours to days, and IaC ensures the reliability of these feedback signals. But feedback only tells you "something is wrong" — it does not tell you "why it is wrong."

Troubleshooting is the final link in the feedback system. When a signal turns red at any layer, the Agent needs to be able to locate the root cause. The quality of this capability determines whether the entire feedback system can truly close the loop.

Agent troubleshooting capability has made substantive progress over the past year. Practitioners have reported scenarios where a bug spans five subsystems — database, cache, frontend, backend API, and object storage — and the Agent autonomously writes diagnostic scripts, queries actual data from each system, compares it against expected values, progressively narrows the scope, and locates the root cause within thirty minutes. This is roughly equivalent to a mid-level engineer who is familiar with the project.

But the ceiling of troubleshooting capability depends on what the Agent can "see". This is where the preceding infrastructure layers prove their value. If logs are structured, metrics are granular, and traces are complete, the Agent has ample information for reasoning. If logs are scattered text, monitoring offers only coarse dashboards, and there are no traces, the Agent faces a nearly undiagnosable black box.

Troubleshooting capability also places demands on platform architecture. One instructive case: separating the UI and rendering layer through a remote protocol produces machine-readable snapshots of UI state. This architectural decision was originally made for other reasons, but it turned out to enable Agents to "see" complex UI states and, combined with debugger skills, diagnose visual bugs that previously only humans could investigate. Which information a platform exposes in machine-readable form directly determines the ceiling of Agent troubleshooting.

There is another shift worth noting. As the workflow moves from humans writing code to humans writing specifications and Agents writing code, the object of debugging also shifts. You used to debug code: set breakpoints, inspect variables, trace execution paths. Now, increasingly, time is spent debugging instructions: modifying prompts, adjusting constraints, optimising context structure, until the Agent's output passes acceptance criteria in one shot and merges directly. The abstraction layer has risen, but the core feedback loop — hypothesise, test, verify, correct — remains fundamentally the same.

This also hints at an extension of platform engineering: building feedback systems not only for the Agent's code output, but also for the human's instruction output. If a particular instruction repeatedly leads to subpar code from the Agent, the platform should detect this pattern and signal to the human: "this instruction may need revision." Feedback does not only flow from the environment to the Agent — it also needs to flow from the Agent's behaviour patterns back to the human operating the Agent.