Cross Reference Manager Dispatcher

Manage and validate cross-platform reference links between GitHub issues, Linear tasks, and other project management tools with integrity checking and automated repair.

When to Use This Command

Run this command when...

• You need to audit the integrity of cross-references between GitHub issues and Linear tasks after a migration or synchronization operation
• You want to add, update, or remove cross-reference links between items on different platforms systematically
• Your cross-platform references have degraded over time with broken links, orphaned references, or missing bidirectional pointers

Do NOT use this command when...

• You need to perform the initial migration of issues -- use bulk import or issue-to-linear commands first
• You want to sync item content rather than just manage the reference links between platforms

Quick Start

Copy
# .claude/commands/cross-reference-manager-dispatcher.md
# Manage cross-platform references
Manage references: $ARGUMENTS

Copy
# Run the command
claude "cross-reference-manager-dispatcher audit and repair broken links between GitHub org/repo and Linear team"

Expected output:
- Reference inventory with link count and health status
- Broken link detection with specific items identified
- Orphaned reference cleanup recommendations
- Repair actions for broken bidirectional links
- Updated reference mapping file

Core Concepts

Concept	Description
Cross-Reference	A link connecting an item on one platform to its counterpart on another
Link Integrity	Verification that both sides of a reference point to valid, existing items
Orphaned Reference	A link pointing to a deleted or moved item on the target platform
Bidirectional Check	Confirming that references exist in both directions (A links to B and B links to A)
Reference Mapping	Persistent store of all cross-platform item relationships

Reference Management Flow:

  Platform A (GitHub)    Platform B (Linear)
       |                      |
  [Scan References]      [Scan References]
       |                      |
  [Build Reference Map]
       |
  [Validate Bidirectional Links]
       |
  +----+----+----+
  |    |    |    |
 Valid Broken Orphan Missing
  |    |    |    |
  [Repair Actions]
       |
  Updated Reference Map

Configuration

Parameter	Default	Description
Platforms	GitHub + Linear	Which platforms to scan for cross-references
Reference Store	.reference-mappings.json	File storing the cross-reference mapping
Audit Scope	Full scan	Whether to audit all references or only recently changed items
Repair Mode	Report only	Whether to automatically repair or just report broken links
Link Format	URL in description	Where cross-references are stored (description, comment, custom field)

Best Practices

1. Run audits after every sync -- cross-reference integrity can degrade after bulk operations. Audit immediately after imports or syncs to catch issues early
2. Store the reference mapping persistently -- commit the .reference-mappings.json file to your repository so the mapping survives across machines and sessions
3. Prefer bidirectional links -- always create references on both platforms so that users on either side can navigate to the counterpart item
4. Handle deletions explicitly -- when an item is deleted on one platform, decide whether to remove the reference or mark it as archived on the other
5. Use stable identifiers -- reference items by unique IDs (issue number, Linear task ID) rather than titles, which may change over time

Common Issues

1. Large reference maps slow down audits -- for repositories with thousands of issues, use incremental audit scope to check only items modified since the last audit
2. References stored inconsistently -- some items may have references in descriptions while others use comments. Standardize the link format before auditing
3. GitHub API rate limits during full scan -- paginated scanning of large repositories may hit rate limits. Use authenticated requests and implement retry with backoff