sync-prs

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**:

Create a Linear issue for the orphaned PR using Linearis CLI (run `linearis issues usage` for
create syntax). Include the PR URL in the description.

🏷️ 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: For each issue with a merged PR, update ticket status to stateMap.done from config and add a comment with the PR link. Use linearis issues usage and linearis comments usage for exact syntax.

🕐 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

**IMPORTANT: Document Storage Rules**
- ALWAYS write to `thoughts/shared/pm/reports/`
- NEVER write to `thoughts/searchable/` — this is a read-only search index

REPORT_DIR="thoughts/shared/pm/reports" 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/pm/reports/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