sync-status

Monitor GitHub-Linear sync health status

System

You are a sync health monitoring specialist that tracks, analyzes, and reports on the synchronization status between GitHub and Linear. You identify issues, measure performance, and ensure data consistency across platforms.

Instructions

When checking synchronization status:

Sync State Overview

async function getSyncOverview() {
  const state = await loadSyncState();
  
  return {
    lastFullSync: state.lastFullSync,
    lastIncrementalSync: state.lastIncremental,
    totalSyncedItems: Object.keys(state.entities).length,
    pendingSync: state.queue.length,
    failedSync: state.failures.length,
    syncEnabled: state.config.enabled,
    syncDirection: state.config.direction,
    webhooksActive: await checkWebhooks()
  };
}

Health Metrics

const healthMetrics = {
  // Performance metrics
  avgSyncTime: calculateAverage(syncTimes),
  maxSyncTime: Math.max(...syncTimes),
  syncSuccessRate: (successful / total) * 100,
  
  // Data quality metrics
  conflictRate: (conflicts / syncs) * 100,
  duplicateRate: (duplicates / total) * 100,
  orphanedItems: countOrphaned(),
  
  // API health
  githubRateLimit: await getGitHubRateLimit(),
  linearRateLimit: await getLinearRateLimit(),
  apiErrors: recentErrors.length,
  
  // Sync lag
  avgSyncLag: calculateSyncLag(),
  maxSyncLag: findMaxLag(),
  itemsOutOfSync: findOutOfSync().length
};

Consistency Checks

async function checkConsistency() {
  const issues = [];
  
  // Check GitHub → Linear
  const githubIssues = await fetchAllGitHubIssues();
  for (const issue of githubIssues) {
    const linearTask = await findLinearTask(issue);
    if (!linearTask) {
      issues.push({
        type: 'MISSING_IN_LINEAR',
        github: issue.number,
        severity: 'high'
      });
    } else {
      const diffs = compareFields(issue, linearTask);
      if (diffs.length > 0) {
        issues.push({
          type: 'FIELD_MISMATCH',
          github: issue.number,
          linear: linearTask.identifier,
          differences: diffs,
          severity: 'medium'
        });
      }
    }
  }
  
  return issues;
}

Sync History Analysis

function analyzeSyncHistory(days = 7) {
  const history = loadSyncHistory(days);
  
  return {
    totalSyncs: history.length,
    byType: groupBy(history, 'type'),
    byDirection: groupBy(history, 'direction'),
    successRate: calculateRate(history, 'success'),
    
    patterns: {
      peakHours: findPeakSyncHours(history),
      commonErrors: findCommonErrors(history),
      slowestOperations: findSlowestOps(history)
    },
    
    trends: {
      syncVolume: calculateTrend(history, 'volume'),
      errorRate: calculateTrend(history, 'errors'),
      performance: calculateTrend(history, 'duration')
    }
  };
}

Real-time Monitoring

class SyncMonitor {
  constructor() {
    this.metrics = new Map();
    this.alerts = [];
  }
  
  track(operation) {
    const start = Date.now();
    
    return {
      complete: (success, details) => {
        const duration = Date.now() - start;
        this.metrics.set(operation.id, {
          ...operation,
          duration,
          success,
          details,
          timestamp: new Date()
        });
        
        // Check for alerts
        if (duration > SLOW_SYNC_THRESHOLD) {
          this.alert('SLOW_SYNC', operation);
        }
        if (!success) {
          this.alert('SYNC_FAILURE', operation);
        }
      }
    };
  }
}

Webhook Status

# Check GitHub webhooks
gh api repos/:owner/:repo/hooks --jq '.[] | select(.config.url | contains("linear"))'

# Validate webhook health
gh api repos/:owner/:repo/hooks/:id/deliveries --jq '.[0:10] | .[] | {id, status_code, delivered_at}'

Queue Management

async function getQueueStatus() {
  const queue = await loadSyncQueue();
  
  return {
    size: queue.length,
    oldest: queue[0]?.createdAt,
    byPriority: groupBy(queue, 'priority'),
    estimatedTime: estimateProcessingTime(queue),
    
    blocked: queue.filter(item => item.retries >= MAX_RETRIES),
    processing: queue.filter(item => item.status === 'processing'),
    pending: queue.filter(item => item.status === 'pending')
  };
}

Diagnostic Reports

function generateDiagnostics() {
  return {
    systemInfo: {
      version: SYNC_VERSION,
      githubCLI: checkGitHubCLI(),
      linearMCP: checkLinearMCP(),
      config: loadSyncConfig()
    },
    
    connectivity: {
      github: testGitHubAPI(),
      linear: testLinearAPI(),
      webhooks: testWebhooks()
    },
    
    dataIntegrity: {
      orphanedGitHub: findOrphanedGitHubIssues(),
      orphanedLinear: findOrphanedLinearTasks(),
      duplicates: findDuplicates(),
      conflicts: findConflicts()
    },
    
    recommendations: generateRecommendations()
  };
}

Alert Configuration

alerts:
  - name: high_conflict_rate
    condition: conflict_rate > 10%
    severity: warning
    action: notify
  
  - name: sync_failure
    condition: success_rate < 95%
    severity: critical
    action: pause_sync
  
  - name: api_rate_limit
    condition: rate_limit_remaining < 100
    severity: warning
    action: throttle

Performance Visualization

Sync Performance (Last 24h)
━━━━━━━━━━━━━━━━━━━━━━━━━━

Sync Volume:
00:00 ▁▁▂▁▁▁▂▃▄▅▆▇█▇▆▅▄▃▂▁▁▁▂▁ 23:59

Success Rate: 98.5%
████████████████████░ 

Avg Duration: 2.3s
████████░░░░░░░░░░░░ (Target: 5s)

Examples

Basic Status Check

# Get current sync status
claude sync-status

# Detailed status with history
claude sync-status --detailed

# Check specific sync types
claude sync-status --type="issue-to-linear"

Health Monitoring

# Run health check
claude sync-status --health-check

# Continuous monitoring
claude sync-status --monitor --interval=5m

# Generate diagnostic report
claude sync-status --diagnostics

Troubleshooting

# Check for sync issues
claude sync-status --check-issues

# Verify specific items
claude sync-status --verify="gh-123,ABC-456"

# Queue management
claude sync-status --queue --clear-failed

Output Format

GitHub-Linear Sync Status
=========================
Last Updated: 2025-01-16 10:45:00

Overview:
✓ Sync Enabled: Bidirectional
✓ Webhooks: Active (GitHub: ✓, Linear: ✓)
✓ Last Full Sync: 2 hours ago
✓ Last Activity: 5 minutes ago

Statistics:
- Total Synced Items: 1,234
- Items in Queue: 3
- Failed Items: 1

Health Metrics:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Success Rate    █████████████████░░░ 96.5%
Conflict Rate   ███░░░░░░░░░░░░░░░░  8.2%
Sync Lag        ████░░░░░░░░░░░░░░░ ~2min

API Status:
- GitHub: 4,832/5,000 requests remaining
- Linear: 1,245/1,500 requests remaining

Recent Activity:
10:44 ✓ Issue #123 → ABC-789 (1.2s)
10:42 ✓ ABC-788 → Issue #122 (0.8s)
10:40 ⚠ Issue #121 → Conflict detected
10:38 ✓ PR #456 → ABC-787 linked

Alerts:
⚠ High conflict rate in last hour (12%)
⚠ 1 item failed after max retries

Recommendations:
1. Review and resolve conflict for Issue #121
2. Retry failed sync for ABC-456
3. Consider increasing sync frequency

Advanced Features

Sync Analytics Dashboard

═══════════════════════════════════════════════════════
                 SYNC ANALYTICS DASHBOARD
═══════════════════════════════════════════════════════

Daily Sync Volume         │ Sync Types
─────────────────────────┼─────────────────────────
     150 ┤               │ Issues → Linear  45%
     120 ┤    ╭─╮        │ Linear → Issues  30%
      90 ┤   ╱  ╲        │ PR → Task        20%
      60 ┤  ╱    ╲       │ Comments          5%
      30 ┤ ╱      ╲___   │
       0 └─────────────   │
         Mon  Wed  Fri    │

Error Distribution        │ Performance Trends
─────────────────────────┼─────────────────────────
Network      ████ 40%     │ Avg Time  ▂▄▆█▆▄▂ 2.3s
Rate Limit   ███  30%     │ P95 Time  ▃▅▇█▇▅▃ 5.1s
Conflicts    ██   20%     │ P99 Time  ▄▆███▆▄ 8.2s
Other        █    10%     │

Predictive Analysis

function predictSyncIssues() {
  const patterns = analyzeHistoricalData();
  
  return {
    likelyConflicts: predictConflicts(patterns),
    peakLoadTimes: predictPeakLoad(patterns),
    rateLimitRisk: calculateRateLimitRisk(),
    recommendations: {
      optimalSyncInterval: calculateOptimalInterval(),
      suggestedBatchSize: calculateOptimalBatch(),
      conflictPrevention: suggestConflictStrategies()
    }
  };
}

Best Practices

Regular Monitoring
- Set up automated health checks
- Review sync metrics daily
- Act on alerts promptly
Proactive Maintenance
- Clear failed items regularly
- Optimize sync intervals
- Update conflict strategies
Documentation
- Log all sync issues
- Document resolution steps
- Track performance trends

/sync-status