bug-triage

name: bug-triage description: 'Systematically investigate Jira tickets to determine root cause and team ownership. Provides a 5-phase workflow for read-only investigation using MCP tools, code search, and data inspection. Outputs standardized markdown reports.' source: internal adopted: 2026-01-30 customizations: OVRC-specific patterns based on 70+ triage investigations license: Internal

Bug Triage Skill

Overview

Investigate bug reports to determine root cause and appropriate team ownership—all through read-only operations. This skill provides a systematic workflow for efficient, evidence-based triage.

When to Use

• User asks to "triage OVRC-12345" or similar
• Investigating a bug report or support escalation
• Determining which team should own a ticket
• Creating a permanent record of bug investigation

⚠️ CRITICAL CONSTRAINT

All operations MUST be read-only. Never:

• Modify databases (MongoDB, Redis)
• Change code in repositories
• Update Jira tickets (no comments, status changes, field updates)
• Execute deployments or configuration changes

If you need to test a hypothesis that requires changes, document the steps for a human to execute.

Phase 1: Gather Context (2-5 min)

Goal

Extract concrete identifiers from the ticket that can be used as search terms.

Workflow

1. Fetch Jira ticket with full details:

   Fetch OVRC-12345 with comment_limit: 50 and fields: *all
   

2. Extract key identifiers:

   • API endpoints (e.g., /v2/customers)
   • Field names (e.g., unverifiedLocationCount)
   • Error messages (exact text)
   • User/location/device IDs
   • Stack traces (file names, line numbers)

3. Check for prior triage in ticket comments

4. Load team ownership files for later reference:

   • inputs/components.yaml
   • inputs/repos.yaml
   • inputs/scopes.yaml

Phase 1 Checklist

• Ticket fetched with comments
• At least one concrete identifier extracted
• Prior triage attempts noted (if any)
• Affected environment identified

Phase 2: Search for Related Issues (2-3 min)

Goal

Determine if this is a known issue, duplicate, or part of a pattern.

Workflow

1. JQL search for similar bugs:

   project = OVRC AND type = Bug AND text ~ "error message pattern"
   

2. Check for existing fixes:

   project = OVRC AND resolution = Fixed AND text ~ "identifier"
   

3. Look for patterns:

   • Same reporter?
   • Same component?
   • Same time period?

Common JQL Patterns

Phase 2 Checklist

• Searched for duplicates
• Checked for prior fixes
• Noted related tickets (if any)

Phase 3: Investigate Root Cause (5-15 min)

Goal

Trace data flow to find where actual behavior diverges from expected behavior.

Strategy

1. Start at the symptom — Where does the user see the problem?
2. Trace backward — Where does that data come from?
3. Find the divergence — Where does logic differ from expectation?

Workflow

1. Search codebase for extracted identifiers:

   grep -r "endpoint_name" mirror/
   grep -r "fieldName" mirror/app-go-api-server/
   

2. Trace data flow:

   • Find API endpoint handler
   • Identify where the problematic field is set
   • Check database queries/transformations
   • Compare with expected behavior

3. Query data if needed (read-only):

   Query devices collection for locationId "abc123" with limit 10
   

4. Check feature flags if behavior seems conditional

Investigation Techniques

Phase 3 Checklist

• Identified affected code path
• Traced data flow
• Found divergence point (or documented where investigation ended)
• Collected code evidence with file paths and line numbers

Phase 4: Determine Team Assignment (1-2 min)

Goal

Route the ticket to the team that owns the affected code.

Workflow

1. Identify affected repository from code investigation
2. Check inputs/repos.yaml for primary ownership
3. Check inputs/components.yaml for Jira component alignment
4. Use inputs/scopes.yaml keywords to confirm domain match
5. Document reasoning

Ownership Decision Tree

Is there a clear affected repository?
├── Yes → Check repos.yaml for team
│   └── Confirm with scopes.yaml keywords
└── No → Check Jira component
    └── Match to components.yaml team

Phase 4 Checklist

• Affected repository identified
• Team assignment matched to ownership files
• Reasoning documented

Phase 5: Generate Triage Report (2-3 min)

Goal

Create a permanent record of the investigation.

Output Location

tickets/{TICKET-KEY}.md (e.g., tickets/OVRC-37942.md)

Required Sections

Every triage report MUST include:

1. TL;DR — One-paragraph summary (root cause + recommendation)
2. Ticket Information — Key fields table
3. Problem Statement — What the user reported
4. Root Cause Analysis — Technical findings with evidence
5. Impact Assessment — Severity, scope, risk
6. Recommendations — Prioritized actions with owners
7. Triage Summary — Team assignment with reasoning

Phase 5 Checklist

• Output file created at tickets/{TICKET-KEY}.md
• All required sections present
• Code evidence includes file paths and line numbers
• Confidence level stated
• Team assignment justified

Triage Report Template

# TICKET-KEY: Brief Summary Title

> **TL;DR**: One-paragraph summary of the problem, root cause, and recommended fix.

---

## Ticket Information

| Field | Value |
|-------|-------|
| **Key** | TICKET-KEY |
| **Summary** | Original ticket summary |
| **Status** | Current status |
| **Priority** | Priority level |
| **Reporter** | Reporter name |
| **Environment** | Affected environment(s) |

---

## Problem Statement

Describe what the user reported:
- Steps to reproduce
- Expected vs actual behavior
- Error messages or screenshots

---

## Root Cause Analysis

### Key Findings

| Finding | Evidence | Impact |
|---------|----------|--------|
| Description | Source (file, line) | User impact |

### Technical Details

- Code paths involved
- Files/repos affected

---

## Impact Assessment

| Dimension | Assessment |
|-----------|------------|
| **Severity** | Low / Medium / High / Critical |
| **Scope** | Who is affected |
| **User Impact** | What users experience |

---

## Recommendations

| Priority | Action | Owner | Notes |
|----------|--------|-------|-------|
| 1 | Primary fix | Team name | Implementation notes |

---

## Triage Summary

| Field | Value |
|-------|-------|
| **Category** | Backend / Frontend / Infrastructure / Data / Not a Defect |
| **Root Cause** | Brief description |
| **Confidence** | Low / Medium / High |
| **Recommended Team** | Team name |
| **Reasoning** | Why this team owns it |

Common Root Cause Categories

Confidence Levels

Jira Comment Template (Wiki Markup)

When providing a comment for the user to paste into Jira:

{quote}
*Root Cause:* Brief description of the root cause.

*Evidence:*
- Code location: [file.go#L123|https://github.com/org/repo/blob/dev/path/file.go#L123]
- Data query results (if applicable)

*Impact:* Who is affected and how.

*Recommended Fix:* What needs to be done.

*Effort Estimate:* X points

*Recommended Team:* Team name
{quote}

Time-Boxing Guidelines

If investigation exceeds 30 minutes:

1. Document findings so far
2. Note specific blockers (e.g., "Need access to production logs")
3. Recommend escalation path
4. Create report with confidence: Low

Example Triage Patterns

Pattern: "Not a Defect"

When behavior is working as designed:

> **TL;DR**: This is **expected behavior**, not a bug. [Explanation of why]...

**Category**: Not a Defect
**Confidence**: High
**Resolution**: Close as "Not a Defect" with explanation

Pattern: "Data Issue"

When the problem is data, not code:

> **TL;DR**: This is a **data issue, not a code bug**. [Missing/incorrect data]...

**Category**: Data / Support
**Recommended Team**: Support / Cloud Services
**Resolution**: Data fix required, not code change

Pattern: "Already Fixed"

When a fix exists but isn't deployed:

> **TL;DR**: This bug was **fixed in PR #1234** but the fix hasn't reached [environment].

**Category**: Deployment
**Recommended Team**: DevOps / Release Management
**Resolution**: Deploy existing fix

Pattern: "Duplicate"

When this is a duplicate of another ticket:

> **TL;DR**: This is a **duplicate of OVRC-12345** which is [status].

**Resolution**: Link as duplicate, close this ticket