ai-bug-fix-triage

Files (1)

• SKILL.md

SKILL.md (first lines)

# Bug Triage

Triage JIRA bugs from a project backlog against a loaded repository to determine which bugs an AI agent can fix. Produces a focused fixability report.

## Scope

This skill answers one question: **can an AI agent fix this bug in this repo?** It classifies issues as AI-Fixable, Needs Human, or Needs Info based on a fixability rubric.

"Bug" is used broadly here — analyze **Bugs and Stories** for fixability. Skip **Epics, Initiatives, and Features** as they are too high-level for a single code fix (note them as skipped in the report).

**Out of scope:**

- **Deduplicate bugs** — does not detect or merge duplicate tickets
- **Prioritize or re-rank severity** — respects the existing JIRA priority as-is
- **Estimate effort** — no story points, t-shirt sizes, or time estimates

## Prerequisites

- **Atlassian MCP** configured and authenticated (provides `getAccessibleAtlassianResources`, `searchJiraIssuesUsingJql`, `getJiraIssue`, `editJiraIssue`, `addCommentToJiraIssue`)
- **Target repository** loaded in the workspace — the user will have it open or will specify it
- **AGENTS.md or CLAUDE.md** present in the repo (used to understand repo structure, test commands, and conventions)

## Usage

```text
User: Triage <PROJECT> bugs against this repo
User: Triage bugs from filter=<ID>
User: Triage project = <PROJECT> AND component = "<component>" AND status = New
User: Triage filter=<ID> and update JIRA with labels
User: Triage just <KEY>
```

## Implementation

### Step 1: Determine the Query, Target Repo, and Scope

**Query:**

1. If the user provides a JQL query, use it directly
2. If the user provides a filter ID, use `filter=<ID>` as the JQL
3. If the user names a component or project, construct JQL defaulting to **untriaged, unassigned** bugs and stories:
   `project = <PROJECT> AND component = "<component>" AND type in (Bug, Story) AND status in (New, Refinement, "To Do") AND assignee is EMPTY ORDER BY priority DESC`
4. If nothing specific is given, ask: "What JQL query or JIRA filter should I use?"

**Target repo:**

1. If the user names a repo, use it
2. If the workspace has a repo loaded, confirm: "I see `<repo>` loaded — should I triage bugs against this repo?"
3. If ambiguous, ask which repo to analyze against

**Repo state (read-only by default):**

Triage is read-only — never switch branches or modify files. Run `git fetch origin` and compare HEAD with `origin/main`. If behind, inform the user but proceed on the current HEAD. Only create a temporary branch (`git checkout -b ai-bug-fix-triage-<date> origin/main`) if the user explicitly asks. State which commit is being used.

### Step 2: Fetch Bugs and Manage Scope

Use the Atlassian MCP `searchJiraIssuesUsingJql` tool. Discover `cloudId` at runtime via `getAccessibleAtlassianResources`. Never hardcode cloud ID or site URL in output, comments, or reports.

```text
Tool: searchJiraIssuesUsingJql
Arguments:
  cloudId: <from getAccessibleAtlassianResources — never hardcode>
  jql: <constructed query>
  maxResults: 50
  responseContentFormat: "markdown"
  fields: ["summary", "description", "status", "issuetype", "priority",
           "labels", "components", "assignee", "created", "updated"]
```

**Fast path vs. interactive path:**

If the user provides a complete request (query + repo + exclusion criteria), proceed directly without stopping to ask questions. Only present scope options when genuinely needed:

- If results exceed one page (50 tickets), offer: narrow scope, work in batches per API page, or process all
- Track `nextPageToken` for iteration resume
- At the end of each batch, display a **progress summary** with cumulative counts:

```text
Processed 50/149+ | Relevant: 5 | AI-Fixable: 2 | Needs Human: 2 | Needs Info: 1 | Not Relevant: 45
Yield: 10% relevant | Continue? (next: 51-100) | "write back" | "stop"
```

When yield drops to zero for a full batch, recommend stopping. If the Not Relevant rate exceeds 80% in the first batch, suggest the user narrow their JQL (e.g., add keywords, restrict issue types, or use a more specific component) before continuing — this avoids burning through batches with low signal.

### Step 3: Filter Out Tickets Not Relevant to This Triage

Before analysis, filter out tickets that are managed elsewhere, irrelevant to the target repo, or already triaged.

**3a. Label-based relevance hints (soft signals)**

Scan each ticket's `labels` field before reading descriptions. Labels are **soft signals**, not definitive — always corroborate with the summary line before classifying as Not Relevant. If there is any doubt, read the description.

| Label pattern | Signal | Action |
|--------------|--------|--------|
| Automation labels (e.g., `auto-created`, `nightly-build`) | Auto-generated by CI/bots | Group together; check which repo's system failed |
| Repo or project name labels | Likely belongs to that repo | Confirm with summary before skipping |
| Technology/platform labels | Platform-specific scope | Narrow relevance, but target repo may still own the fix |
| Process/workflow labels | Organizational context | Check if they match the target repo's domain |

**3b. Skip already-triaged bugs (idempotency)**

Check each bug's labels for an existing classification label (`ai-fixable`, `ai-nonfixable`, `ai-needs-info`):

- **`ai-fixable` or `ai-nonfixable`**: Already triaged — skip by default.
- **`ai-needs-info`**: Always re-evaluate. Fetch full issue details via `getJiraIssue` to access comments and their timestamps. Check for replies posted after the original triage comment. If new information was provided, re-run the fixability analysis and update the classification. If no new info, skip.

Report: `Skipped: N tickets already classified (M ai-needs-info re-evaluated after new comments)`.

If the user explicitly requests re-triage (e.g., "re-triage everything"), process all tickets regardless of existing labels. Compare the new classification to the old and note any changes.

**3c. Ask about additional exclusion criteria** rather than assuming. Present observed patterns:

```text
I see the following patterns in the results:
  - N tickets with labels [auto-created, nightly-build] — are these handled by automation?
  - N tickets already assigned to someone — include or skip?
  - N tickets with status "Closed" or "Done" — skip these?
Which of these should I exclude?
```

From jeremyeder/ai-helpers-plugin, Apache-2.0.

More from jeremyeder/ai-helpers-plugin