/cross-reference-manager

Cross-Reference Manager

Manage cross-platform reference links

Instructions

1. **Check Tool Availability**

• Verify GitHub CLI (`gh`) is installed and authenticated
• Check if Linear MCP server is connected
• If either tool is missing, provide setup instructions

2. **Parse Command Arguments**

• Extract the action from command arguments: **$ARGUMENTS**
• Valid actions: audit, repair, map, validate, export
• Parse any additional options provided

3. **Initialize Reference Database**

• Create or load existing reference mapping database
• Structure should track:
• GitHub issue ID ↔ Linear task ID
• GitHub PR ID ↔ Linear task ID
• Comment references
• User mappings
• Timestamps and sync history

4. **Execute Selected Action** Based on the action provided:

Audit Action

• Scan all GitHub issues and PRs for Linear references
• Query Linear for all tasks with GitHub references
• Identify:
• Orphaned references (deleted items)
• Mismatched references
• Duplicate mappings
• Missing bidirectional links
• Generate detailed audit report

Repair Action

• Fix identified reference issues:
• Update Linear tasks with missing GitHub links
• Add Linear references to GitHub items
• Remove references to deleted items
• Consolidate duplicate mappings
• Create backup before making changes
• Log all modifications

Map Action

• Display current reference mappings
• Show visual representation of connections
• Include statistics on reference health
• Highlight problematic mappings

Validate Action

• Perform deep validation of references
• Check that linked items actually exist
• Verify field consistency
• Test bidirectional navigation
• Report validation results

Export Action

• Export reference data in multiple formats
• Support JSON, CSV, and Markdown
• Include metadata and history
• Provide import instructions

Usage

cross-reference-manager [action] [options]

Actions

• `audit` - Scan and report on reference integrity
• `repair` - Fix broken or missing references
• `map` - Display reference mappings
• `validate` - Verify reference consistency
• `export` - Export reference data

Options

• `--scope <type>` - Limit to specific types (issues, prs, tasks)
• `--fix-orphans` - Automatically fix orphaned references
• `--dry-run` - Preview changes without applying
• `--deep-scan` - Perform thorough validation
• `--format <type>` - Output format (json, csv, table)
• `--since <date>` - Process items created after date
• `--backup` - Create backup before modifications

Examples

# Audit all references
cross-reference-manager audit

# Repair broken references with preview
cross-reference-manager repair --dry-run

# Map references for specific date range
cross-reference-manager map --since "2024-01-01"

# Deep validation with orphan fixes
cross-reference-manager validate --deep-scan --fix-orphans

# Export reference data
cross-reference-manager export --format json > refs.json

Features

• **Reference Integrity Checking**
• Verify bidirectional links
• Detect orphaned references
• Identify duplicate mappings
• Check reference format validity

• **Smart Reference Repair**
• Reconstruct missing references from metadata
• Update outdated reference formats
• Merge duplicate references
• Remove invalid references

• **Comprehensive Mapping**
• GitHub Issue ↔ Linear Issue
• GitHub PR ↔ Linear Task
• Comments and attachments
• User mappings

• **Audit Trail**
• Log all reference modifications
• Track reference history
• Generate integrity reports
• Monitor reference health

Reference Storage

{
  "mappings": {
    "github_issue_123": {
      "linear_id": "LIN-456",
      "type": "issue",
      "created": "2024-01-15T10:30:00Z",
      "last_verified": "2024-01-20T14:00:00Z",
      "confidence": 0.95
    }
  },
  "metadata": {
    "last_audit": "2024-01-20T14:00:00Z",
    "total_references": 1543,
    "broken_references": 12
  }
}

Error Handling

• Automatic retry for API failures
• Batch processing to avoid rate limits
• Transaction-like operations with rollback
• Detailed error logging

Best Practices

• Run audit weekly to maintain integrity
• Always use --dry-run before repair operations
• Export references before major changes
• Monitor reference health metrics

Integration Points

• Works with bidirectional-sync command
• Supports sync-status monitoring
• Compatible with migration-assistant
• Provides data for analytics

Required MCP Servers

• mcp-server-github
• mcp-server-linear

Notes

This command maintains a local reference database for performance and reliability. The database is automatically backed up before modifications.