Skip to content

14. Issue Triage & Root Cause
What When an issue is reported, the team establishes its root cause and captures a complete documented record (problem statement, root cause, solution options with estimates) in a JIRA ticket, so it can be scheduled later without re-investigating and nothing is lost.
Owner The senior developer investigating establishes the root cause and, when it is clear, the solution and estimate. The engineering manager / head of engineering (a Leadership duty) is engaged only when the cause or the solution cannot be settled by the developer alone. The Product Owner documents the ticket; the Project Manager ensures the SOP is followed.
Triggers Whenever an issue is reported, from any source (Support, post-production monitoring, or internally) and at any time. It is not tied to a fixed point in the lifecycle.

Summary

Issues surface unpredictably: a client reports one through Support, monitoring flags one, or a developer spots one. Whatever the source, the moment an issue is raised is when the most context exists about it, and that context is easy to lose if the fix does not happen right away. This SOP captures it while it is fresh. A senior developer investigates and establishes the root cause. If the cause is clear and they can definitively decide the solution and its estimate, they proceed; if not, they engage the engineering manager to vet the cause and settle the approach. Either way, the Product Owner records everything (problem statement, root cause, each solution option, and an estimate for each) in a JIRA ticket, whether or not the fix is done immediately. The result is that a problem picked up weeks later starts from a complete record rather than from scratch, and the Product Owner can prioritize it with real estimates in hand.

Full detail

Why this exists

Issues arrive at any time and from anywhere in the product. The risk is not the issue itself, it is losing the fresh investigation: what was looked into, what is believed to be wrong, and what a fix would take. If that is not written down while it is fresh, then a fix deferred by three weeks starts over from nothing, and some issues quietly drop off entirely. Documenting every reported issue at the point of investigation is what prevents both.

The flow

  1. Root cause first (Developer). The senior developer investigating establishes the root cause, following the debugging order: monitoring tools first, then application logs and the user journey. Analysis comes before any code.

  2. Decide the solution, or escalate if you cannot. When the root cause is clear and the developer can definitively decide the solution and its estimate, they proceed on their own. The engineering manager / head of engineering (a Leadership responsibility) is engaged only when:

    • the root cause is not clear, or
    • the developer cannot definitively say which solution to take, or how long it will take, or which of several candidate solutions to pick.

    In those cases the manager vets the root cause and helps settle the approach; otherwise no escalation is needed. 3. Fix now or later, but always document. If a solution is small and safe enough to do there and then, it can be done immediately. In every case a JIRA ticket is still created: an immediate fix does not skip the record. 4. Document the ticket (Product Owner). The Product Owner creates and owns the JIRA ticket, capturing, while the investigation is fresh: the problem statement (what is happening and its impact), the root cause, each candidate solution, and a time estimate for each solution. Use the Issue analysis record template. 5. Prioritize (Product Owner). With estimates recorded, the Product Owner decides when the fix is scheduled. Urgent issues that cannot wait go to Hotfix; the rest enter a future release through Backlog & Grooming and Planning & Estimation. 6. Oversight (Project Manager). The Project Manager ensures this SOP is followed for every reported issue, so nothing is investigated and then quietly dropped.

What every reported issue must capture

  • Problem statement: what is going wrong and its impact on clients or the business.
  • Root cause: established by the developer, evidence based.
  • Solution options: one or more candidate approaches, escalated to the engineering manager only when the developer cannot settle them alone.
  • Estimate per option: rough effort for each, so the fix can be scheduled realistically.

The root cause captured here is the same evidence that later feeds Escaped Defects Analysis if the issue is classified as an escaped defect.

flowchart TD
    A[Issue reported: any source, any time] --> B[Senior developer investigates and establishes root cause]
    B --> C{Cause clear and solution + estimate definitive?}
    C -->|no: unclear cause, or must choose an option / set estimate| D[Engage engineering manager to vet cause and settle solution]
    C -->|yes| E[Product Owner documents JIRA ticket: problem, root cause, solutions, estimates]
    D --> E
    E --> F{Product Owner decides disposition}
    F -->|small and safe| G[Fix now, ticket records it]
    F -->|urgent, cannot wait| H[Hotfix]
    F -->|can wait| I[Backlog & Grooming then Planning]

The Project Manager ensures the SOP is followed end to end, so every reported issue leaves a documented record no matter its disposition.

Example

A client reports through Support that a discount occasionally applies twice on split bills. The developer investigates: New Relic shows no error spike, so they trace the Google Cloud Console logs and find the discount is re-applied when a bill is split after the discount is set (the root cause). Here the cause is clear but there are two viable fixes with very different costs: a quick guard that blocks re-application (about half a day) or a larger refactor of how discounts attach to bill items (several days, but it removes the whole class of bug). Because the developer cannot definitively pick between them, they bring it to the engineering manager, who weighs the trade-off. The Product Owner then creates ticket ABC-1500 documenting the problem, the root cause, and both options with their estimates. It is not affecting all clients, so it is scheduled into an upcoming sprint rather than hotfixed. Three weeks later the team picks it up straight from the documented ticket, with no re-investigation.