triage-issue

What this skill does

# Triage Issue

## Keywords
triage bug, check duplicate, is this a duplicate, search for similar issues, create bug ticket, file a bug, report this error, triage this error, bug report, error message, similar issues, duplicate bug, who fixed this, has this been reported, search bugs, find similar bugs, create issue, file issue

## Overview

Automatically triage bug reports and error messages by searching Jira for duplicates, identifying similar past issues, and helping create well-structured bug tickets or add context to existing issues. This skill eliminates manual duplicate checking and ensures bugs are properly documented with relevant historical context.

**Use this skill when:** Users need to triage error messages, bug reports, or issues to determine if they're duplicates and take appropriate action.

---

## Workflow

Follow this 6-step process to effectively triage issues:

### Step 1: Extract Key Information

Analyze the bug report or error message to identify search terms.

#### Extract These Elements:

**Error signature:**
- Error type or exception name (e.g., "NullPointerException", "TimeoutError")
- Error code or status (e.g., "500", "404", "ERR_CONNECTION_REFUSED")
- Specific error message text (key phrases, not full stack trace)

**Context:**
- Component or system affected (e.g., "authentication", "payment gateway", "API")
- Environment (e.g., "production", "staging", "mobile app")
- User actions leading to error (e.g., "during login", "when uploading file")

**Symptoms:**
- Observable behavior (e.g., "page blank", "infinite loading", "data not saving")
- Impact (e.g., "users can't login", "payments failing")

#### Example Extractions:

**Input:** "Users getting 'Connection timeout' error when trying to login on mobile app"
**Extracted:**
- Error: "Connection timeout"
- Component: "login", "mobile app"
- Symptom: "can't login"

**Input:** "NullPointerException in PaymentProcessor.processRefund() line 245"
**Extracted:**
- Error: "NullPointerException"
- Component: "PaymentProcessor", "refund"
- Location: "processRefund line 245"

---

### Step 2: Search for Duplicates

Search Jira using extracted keywords to find similar or duplicate issues.

#### Search Strategy:

Execute **multiple targeted searches** to catch duplicates that may use different wording:

**Search 1: Error-focused**
```
searchJiraIssuesUsingJql(
  cloudId="...",
  jql='project = "PROJ" AND (text ~ "error signature" OR summary ~ "error signature") AND type = Bug ORDER BY created DESC',
  fields=["summary", "description", "status", "resolution", "created", "updated", "assignee"],
  maxResults=20
)
```

**Search 2: Component-focused**
```
searchJiraIssuesUsingJql(
  cloudId="...",
  jql='project = "PROJ" AND text ~ "component keywords" AND type = Bug ORDER BY updated DESC',
  fields=["summary", "description", "status", "resolution", "created", "updated", "assignee"],
  maxResults=20
)
```

**Search 3: Symptom-focused**
```
searchJiraIssuesUsingJql(
  cloudId="...",
  jql='project = "PROJ" AND summary ~ "symptom keywords" AND type = Bug ORDER BY priority DESC, updated DESC',
  fields=["summary", "description", "status", "resolution", "created", "updated", "assignee"],
  maxResults=20
)
```

#### Search Tips:

**Use key terms only:**
- ✅ "timeout login mobile"
- ✅ "NullPointerException PaymentProcessor refund"
- ❌ "Users are getting a connection timeout error when..." (too verbose)

**Search recent first:**
- Order by `created DESC` or `updated DESC` to find recent similar issues
- Recent bugs are more likely to be relevant duplicates

**Don't over-filter:**
- Include resolved issues (might have been reopened or regression)
- Search across all bug statuses to find fix history

---

### Step 3: Analyze Search Results

Evaluate the search results to determine if this is a duplicate or a new issue.

#### Duplicate Detection:

**High confidence duplicate (>90%):**
- Exact same error message in summary or description
- Same component + same error type
- Recent issue (< 30 days) with identical symptoms
- **Action:** Strongly recommend adding comment to existing issue

**Likely duplicate (70-90%):**
- Similar error with slight variations
- Same component but different context
- Resolved issue with same root cause
- **Action:** Present as possible duplicate, let user decide

**Possibly related (40-70%):**
- Similar symptoms but different error
- Same component area but different specific error
- Old issue (> 6 months) that might be unrelated
- **Action:** Mention as potentially related

**Likely new issue (<40%):**
- No similar issues found
- Different error signature and component
- Unique symptom or context
- **Action:** Recommend creating new issue

#### Check Fix History:

If similar resolved issues are found:

**Extract relevant information:**
- Who fixed it? (assignee on resolved issues)
- How was it fixed? (resolution comment or linked PRs)
- When was it fixed? (resolution date)
- Has it regressed? (any reopened issues)

**Present this context** to help with triage decision.

---

### Step 4: Present Findings to User

**CRITICAL:** Always present findings and wait for user decision before taking any action.

#### Format for Likely Duplicate:

```
🔍 **Triage Results: Likely Duplicate**

I found a very similar issue already reported:

**PROJ-456** - Connection timeout during mobile login
Status: Open | Priority: High | Created: 3 days ago
Assignee: @john.doe
https://yoursite.atlassian.net/browse/PROJ-456

**Similarity:**
- Same error: "Connection timeout"
- Same component: Mobile app login
- Same symptoms: Users unable to login

**Difference:**
- Original report mentioned iOS specifically, this report doesn't specify platform

**Recommendation:** Add your details as a comment to PROJ-456

Would you like me to:
1. Add a comment to PROJ-456 with your error details
2. Create a new issue anyway (if you think this is different)
3. Show me more details about PROJ-456 first
```

#### Format for Possibly Related:

```
🔍 **Triage Results: Possibly Related Issues Found**

I found 2 potentially related issues:

**1. PROJ-789** - Mobile app authentication failures
Status: Resolved | Fixed: 2 weeks ago | Fixed by: @jane.smith
https://yoursite.atlassian.net/browse/PROJ-789

**2. PROJ-234** - Login timeout on slow connections
Status: Open | Priority: Medium | Created: 1 month ago
https://yoursite.atlassian.net/browse/PROJ-234

**Assessment:** Your error seems related but has unique aspects

**Recommendation:** Create a new issue, but reference these related tickets

Would you like me to create a new bug ticket?
```

#### Format for No Duplicates:

```
🔍 **Triage Results: No Duplicates Found**

I searched Jira for:
- "Connection timeout" errors
- Mobile login issues
- Authentication failures

No similar open or recent issues found.

**Recommendation:** Create a new bug ticket

**Note:** I found 1 old resolved issue (PROJ-123 from 8 months ago) about login timeouts, but it was for web, not mobile, and was resolved as "configuration error."

Would you like me to create a new bug ticket for this issue?
```

---

### Step 5: Execute User Decision

Based on user's choice, either add a comment or create a new issue.

#### Option A: Add Comment to Existing Issue

If user wants to add to existing issue:

**Fetch the full issue first** to understand context:
```
getJiraIssue(
  cloudId="...",
  issueIdOrKey="PROJ-456"
)
```

**Then add the comment:**
```
addCommentToJiraIssue(
  cloudId="...",
  issueIdOrKey="PROJ-456",
  commentBody="[formatted comment - see below]"
)
```

**Comment Structure:**
```markdown
## Additional Instance Reported

**Reporter:** [User's name or context]
**Date:** [Current date]

**Error Details:**
[Paste relevant error message or stack trace]

**Context:**
- Environment: [e.g., Production, iOS 16.5]
- User Impact: [e.g., 50+ users affected in last hour]
- Steps to Reproduce: [if provided]

**Additional Notes:**
[Any unique aspects of this instance]

---
*Added via triage