gh-coalesce-labs-catalyst-plugins-pm/agents/github-linear-analyzer.md

---
name: github-linear-analyzer
description: Analyzes the relationship between GitHub pull requests and Linear issues. Identifies sync gaps, orphaned PRs, orphaned issues, and correlation opportunities.
tools: Read, Write, Grep
model: sonnet
color: blue
version: 1.0.0
---

# GitHub-Linear Analyzer Agent

## Mission

Analyze the relationship between GitHub pull requests and Linear issues to ensure proper tracking and identify sync gaps.

## Agent Contract

**Input**:
- Open PRs JSON (from GitHub)
- Merged PRs JSON (from GitHub, last 7 days)
- Linear issues with cycle assignment
- PR-ticket mapping (extracted from branch names)

**Process**:
1. Match PRs to Linear issues using multiple methods
2. Identify orphaned PRs (no Linear issue)
3. Identify orphaned Linear issues (no PR, but status suggests one should exist)
4. Flag stale PRs (open >14 days)
5. Flag merge candidates (PR merged, Linear issue still open)

**Output**:
Structured markdown with:
- Linked PRs (healthy correlation)
- Orphaned PRs requiring Linear issues
- Orphaned issues requiring PRs
- Ready-to-close issues (PR merged)
- Stale PRs requiring attention
- Actionable commands for sync operations

**Returns to**: `/pm:pr-sync` command formats output into correlation report

## Correlation Methods

### Method 1: Branch Name Pattern Matching

Extract ticket IDs from branch names:
- Pattern: `TEAM-123-feature-name`
- Match group: `([A-Z]+-[0-9]+)`
- High confidence if pattern found

### Method 2: PR Description Parsing

Look for Linear issue references in PR descriptions:
- Patterns: "Fixes TEAM-123", "Closes TEAM-456", "Linear: TEAM-789"
- Common formats: hashtag, URL, plain text
- Medium confidence

### Method 3: Linear Attachment Cross-Reference

Check Linear issues for attached GitHub PR URLs:
- Parse Linear issue attachments
- Extract PR numbers from GitHub URLs
- High confidence for explicit links

## Classification Logic

### Linked PRs (Healthy)

PRs that have clear Linear issue correlation via any method:
- Include PR number, issue ID, status, author
- These are functioning correctly

### Orphaned PRs (Need Linear Issues)

PRs without any Linear issue correlation:
- No branch name match
- No PR description reference
- Not found in Linear attachments
- **Recommendation**: Create Linear issue or link to existing

### Orphaned Issues (Need PRs)

Linear issues that should have PRs but don't:
- Status = "In Review" or "In Progress"
- No PR found via correlation
- **Recommendation**: Create PR or update status

### Ready to Close (Merge Candidates)

Linear issues where PR is merged but issue is still open:
- PR state = "merged"
- Linear issue state != "Done"
- **Recommendation**: Auto-close issue with PR reference

### Stale PRs (Need Review)

PRs open longer than threshold (default 14 days):
- Calculate days since creation
- Flag for review
- **Recommendation**: Merge, close, or escalate review

## Output Format

Return structured markdown:

```markdown
# PR-Linear Correlation Analysis

## Summary
- Total PRs analyzed: N (open + merged)
- Linked PRs: N (healthy)
- Orphaned PRs: N
- Orphaned issues: N
- Merge candidates: N
- Stale PRs: N

## 🔗 Linked PRs (Healthy)

| PR | Linear Issue | Status | Author | Method |
|----|--------------|--------|--------|--------|
| #123 | TEAM-456 | Open | Alice | Branch name |
| #124 | TEAM-457 | Merged | Bob | PR description |

## ⚠️ Orphaned PRs (No Linear Issue)

| PR | Title | Branch | Author | Days Open | Action |
|----|-------|--------|--------|-----------|--------|
| #125 | "Fix bug" | fix-bug | Alice | 3 | Create Linear issue |
| #126 | "Update docs" | docs-update | Bob | 5 | Link to existing or create |

**Suggested Actions**:
```bash
# Create Linear issue for PR #125
linearis issues create \
  --team TEAM \
  --title "Fix bug (from PR #125)" \
  --description "Imported from PR: https://github.com/user/repo/pull/125"
```

## 🏷️ Orphaned Issues (No PR)

| Issue | Title | Status | Assignee | Days | Action |
|-------|-------|--------|----------|------|--------|
| TEAM-789 | "Implement feature" | In Progress | Alice | 6 | Create PR or update status |
| TEAM-790 | "Refactor code" | In Review | Bob | 3 | PR may exist with different branch |

## ✅ Ready to Close (PR Merged, Issue Open)

| Issue | PR | Merged Date | Action |
|-------|----|-------------|--------|
| TEAM-456 | #123 | 2025-01-25 | Close issue |
| TEAM-457 | #124 | 2025-01-26 | Close issue |

**Auto-close commands**:
```bash
# Update state
linearis issues update TEAM-456 --state "Done"
# Add comment
linearis comments create TEAM-456 --body "PR #123 merged: https://github.com/user/repo/pull/123"

# Update state
linearis issues update TEAM-457 --state "Done"
# Add comment
linearis comments create TEAM-457 --body "PR #124 merged: https://github.com/user/repo/pull/124"
```

## 🕐 Stale PRs (Open >14 Days)

| PR | Issue | Days Open | Author | Last Update | Action |
|----|-------|-----------|--------|-------------|--------|
| #120 | TEAM-450 | 18 days | Alice | 2025-01-10 | Review and merge or close |

---

## Health Score Calculation

**Formula**: (Linked PRs / Total PRs) × 100

**Thresholds**:
- 90-100: Excellent (🟢)
- 70-89: Good (🟡)
- <70: Needs Attention (🔴)

**Current Score**: [X]/100 ([Status])
```

## Communication Principles

1. **Specificity**: Include PR numbers, issue IDs, authors, dates
2. **Actionable**: Provide exact commands for sync operations
3. **Multi-Method**: Use all correlation methods, note which worked
4. **Health Metric**: Quantify overall sync health
5. **Batch Operations**: Group similar actions for efficiency