Sync PRs Command

Analyzes the relationship between GitHub pull requests and Linear issues to identify:

• PRs without linked Linear issues
• Linear issues without associated PRs
• Merged PRs with open Linear issues (candidates for closure)
• Open PRs for completed Linear issues (stale PRs)

Prerequisites Check

# 1. Validate thoughts system (REQUIRED)
if [[ -f "scripts/validate-thoughts-setup.sh" ]]; then
  ./scripts/validate-thoughts-setup.sh || exit 1
else
  # Inline validation if script not found
  if [[ ! -d "thoughts/shared" ]]; then
    echo "❌ ERROR: Thoughts system not configured"
    echo "Run: ./scripts/humanlayer/init-project.sh . {project-name}"
    exit 1
  fi
fi

# 2. Determine script directory with fallback
if [[ -n "${CLAUDE_PLUGIN_ROOT}" ]]; then
  SCRIPT_DIR="${CLAUDE_PLUGIN_ROOT}/scripts"
else
  # Fallback: resolve relative to this command file
  SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/scripts"
fi

# 3. Check PM plugin prerequisites
if [[ -f "${SCRIPT_DIR}/check-prerequisites.sh" ]]; then
  "${SCRIPT_DIR}/check-prerequisites.sh" || exit 1
else
  echo "⚠️ Prerequisites check skipped (script not found at: ${SCRIPT_DIR})"
fi

Process

Step 1: Spawn Research Tasks (Parallel)

# Determine script directory with fallback
if [[ -n "${CLAUDE_PLUGIN_ROOT}" ]]; then
  SCRIPT_DIR="${CLAUDE_PLUGIN_ROOT}/scripts"
else
  # Fallback: resolve relative to this command file
  SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/scripts"
fi

source "${SCRIPT_DIR}/pm-utils.sh"
TEAM_KEY=$(get_team_key)

Task 1 - Get GitHub PRs: Use catalyst-dev:github-research agent (if exists) or inline gh commands:

Get open and recently merged PRs (last 7 days)

Task 2 - Get Linear Issues: Use Task tool with catalyst-dev:linear-research agent:

Prompt: "Get all in-review and in-progress issues for team ${TEAM_KEY}"
Model: haiku

Wait for both tasks to complete

Step 2: Spawn Analysis Agent

Use Task tool with github-linear-analyzer agent:

Input:

• GitHub PRs from Task 1
• Linear issues from Task 2

Output:

• Linked PRs (healthy)
• Orphaned PRs (no Linear issue)
• Orphaned issues (no PR)
• Ready to close (PR merged, issue open)
• Stale PRs (>14 days)

Step 3: Generate Sync Report

# PR-Linear Sync Report

**Generated**: 2025-01-27
**Repository**: user/repo
**Linear Team**: TEAM

## 📊 Summary

- Open PRs: 12 (8 linked, 4 orphaned)
- Merged PRs (7d): 15 (13 linked, 2 orphaned)
- Linear issues in review: 10 (8 with PRs, 2 without)

## 🔗 Linked PRs (Healthy)

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

## ⚠️ Orphaned PRs (No Linear Issue)

| PR | Title | Branch | Author | Action |
|----|-------|--------|--------|--------|
| #125 | "Fix bug" | fix-bug | Alice | Create Linear issue or link existing |
| #126 | "Update docs" | docs-update | Bob | Create Linear issue or link existing |

**Recommended 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"

# Or manually link in Linear UI

🏷️ Orphaned Issues (No PR)

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

✅ Ready to Close (PR merged, issue open)

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

Auto-close commands:

# 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	Action
#120	TEAM-450	18 days	Alice	Review and merge or close

### Step 4: Save Report

```bash
REPORT_DIR="thoughts/shared/reports/pr-sync"
mkdir -p "$REPORT_DIR"

REPORT_FILE="$REPORT_DIR/$(date +%Y-%m-%d)-pr-sync.md"

# Write formatted report to file
cat > "$REPORT_FILE" << EOF
# PR-Linear Sync Report - $(date +%Y-%m-%d)

[... formatted report content ...]
EOF

echo "✅ Report saved: $REPORT_FILE"

# Update workflow context
if [[ -f "${SCRIPT_DIR}/workflow-context.sh" ]]; then
  "${SCRIPT_DIR}/workflow-context.sh" add reports "$REPORT_FILE" null
fi

Step 5: Display Summary

🔗 PR-Linear Sync Report

Health Score: 75/100
  ✅ 8 properly linked PRs
  ⚠️ 4 orphaned PRs need Linear issues
  ⚠️ 2 orphaned issues need PRs
  ✅ 2 ready to close

Actions available:
  1. Auto-close merged issues (generates commands)
  2. Create Linear issues for orphaned PRs
  3. View full report

Full report: thoughts/shared/reports/pr-sync/2025-01-27-pr-sync.md

Success Criteria

Automated Verification:

• GitHub PR data fetched successfully
• Linear issue data fetched successfully
• PR-ticket correlation logic executes
• Report generated with all sections
• Auto-close commands are valid

Manual Verification:

• PR-issue matches are accurate
• Orphaned detection has minimal false positives
• Branch name extraction works correctly
• Recommendations are actionable
• Report provides clear next steps