linear-bug

name	linear-bug
description	Investigate a bug or issue reported in a Linear ticket. Identify root cause, assess impact, implement the fix, and open a pull request.
scopes	["linear","slack"]

Linear Bug

Investigate a bug or issue from a Linear ticket, fix it, and open a pull request.

Use the linear plugin tools (linear_issue_view, linear_issue_update, linear_issue_create, linear_comment_add, etc.) for all API operations.

Phase 1: Gather Context

1. Fetch the ticket with linear_issue (action: view) — read the title, description, comments, and any error details.
2. Check for existing triage work — if the description already contains a ## Triage Report, a root cause analysis, or affected code paths from a prior run, use that as your starting point — do not re-investigate from scratch unless the ticket or a comment explicitly asks you to.
3. Identify the reported symptoms: what's broken, when it started, who's affected, any reproduction steps.
4. Check linked issues and parent/child relationships for related context.

Phase 2: Reproduce & Trace

1. Locate the code path — based on the symptoms, find the entry point and trace the execution flow. Use explorer for unfamiliar areas.
2. Read the relevant code — don't skim, read carefully. Pay attention to:
   • Error handling (or lack thereof)
   • Edge cases in conditionals
   • Assumptions about input data
   • Recent changes (git log / git blame on suspect files)
3. Check related systems — if the bug involves external APIs, databases, or services, check configuration, env vars, and integration code.
4. Look for patterns — search for similar bugs in the codebase. Has this class of bug happened before?

Phase 3: Root Cause Analysis

Identify the root cause, not just the trigger. Ask:

• Why does this code path fail? (immediate cause)
• Why was the code written this way? (design decision)
• Why wasn't this caught by tests? (test gap)

Phase 4: Write the Triage Report

Append the report to the ticket description (use linear_issue action: update with appendDescription: true). Do NOT use comments.

Report Structure

---

## Triage Report

### Root Cause
[What's broken and why — specific file paths, function names, line numbers]

### Reproduction
[Steps to trigger the bug, or why it's intermittent]

### Affected Code
- `path/to/file.ts:42` — [what's wrong here]
- `path/to/other.ts:108` — [related issue]

### Impact Assessment
- **Severity**: [Critical / High / Medium / Low]
- **Scope**: [All users / specific conditions / edge case]
- **Workaround**: [Available / None — describe if available]

### Fix Applied
[What was changed and why — branch name, files modified]

### Risk Assessment
[What could go wrong with the fix, what else might break, what to test]

### Test Gaps
[What tests were added or should be added to prevent regression]

Phase 5: Check In-Flight Work

Before implementing the fix, scan for concurrent work that might overlap with your changes.

1. Query Linear for in-progress and in-review tickets on the same team:
   • linear_issue list --team <TEAM> --state "In Progress"
   • linear_issue list --team <TEAM> --state "In Review"
2. Query GitHub for open PRs on the target repo:
   • gh pr list --state open --json number,title,headRefName,changedFiles,additions,deletions
3. Identify overlaps — tickets or PRs that touch the same files, same feature area, or are explicitly related (linked issues, dependency chains).
4. Decide how to proceed:
   • No overlap → proceed normally (branch off main).
   • Prerequisite PR exists (your fix depends on changes in an open PR) → branch off that PR's branch instead of main.
   • Parallel but overlapping PR (touches the same files but isn't a dependency) → read its diff to understand what's changing and avoid conflicts.
   • Note any overlaps in the triage report so reviewers have context.

Phase 6: Implement the Fix

1. Start from latest main (or a prerequisite PR's branch if Phase 5 identified one) — fetch and reset.
2. Create a feature branch — name it after the issue (e.g. eng-42-fix-null-check).
3. Work in a git worktree to isolate your changes.
4. Implement the fix, following existing codebase patterns.
5. Add tests to cover the bug — at minimum a regression test for the exact scenario.
6. Run the build and tests to verify your changes.
7. Commit with clear messages.
8. Open a PR with the triage report context and a description of what changed and why.

If the fix turns out to be too complex (touches many modules, needs architectural changes, has unclear scope):

• Post the triage report on the ticket without a fix.
• Add the #prep label to signal it needs prep (sizing, context enrichment) first.
• Explain in the report why a direct fix isn't feasible.

Output Summary

After opening the PR, respond with:

1. One-sentence root cause
2. Severity assessment
3. Link to the PR

Notes

• Be specific — file paths, line numbers, function names. Vague triage is useless triage.
• Always append to the ticket description — preserve existing content.
• Check git history — git log and git blame on suspect files often reveal when the bug was introduced and why.
• Don't guess — if you can't determine the root cause with confidence, say so and list what additional information is needed.
• Fix the root cause, not just the symptom. A null check might stop the crash, but the real fix might be ensuring the data is never null in the first place.