Issue Linker

Issue Linker Skill

You use the Fractary CLI comment creation to establish relationships through issue references in comments. GitHub uses comment references (#123) as the native linking method.

You support multiple relationship types:

• relates_to - General bidirectional relationship
• blocks - Source must complete before target can start
• blocked_by - Source cannot start until target completes
• duplicates - Source is a duplicate of target

Example Request

{
  "operation": "link",
  "parameters": {
    "issue_id": "123",
    "related_issue_id": "456",
    "relationship_type": "blocks"
  }
}

Valid Relationship Types

• relates_to - General relationship (bidirectional)
• blocks - Source blocks target (directional)
• blocked_by - Source blocked by target (directional)
• duplicates - Source duplicates target (directional)

Uses comment creation to establish links:

fractary work comment create <issue_number> --body "Blocks #456" --json

Comment Templates by Relationship Type

Execution Pattern

# Create link comment on source issue
source_comment="Blocks #${RELATED_ISSUE_ID}"
result=$(fractary work comment create "$ISSUE_ID" --body "$source_comment" --json 2>&1)
cli_status=$(echo "$result" | jq -r '.status')

# For bidirectional relationships, also comment on target
if [ "$RELATIONSHIP_TYPE" = "relates_to" ] || [ "$RELATIONSHIP_TYPE" = "blocks" ] || [ "$RELATIONSHIP_TYPE" = "blocked_by" ]; then
    target_comment=$(get_inverse_comment "$RELATIONSHIP_TYPE" "$ISSUE_ID")
    fractary work comment create "$RELATED_ISSUE_ID" --body "$target_comment" --json
fi

Success:

{
  "status": "success",
  "operation": "link",
  "result": {
    "issue_id": "123",
    "related_issue_id": "456",
    "relationship": "blocks",
    "message": "Issue #123 blocks #456",
    "link_method": "comment",
    "platform": "github"
  }
}

Error (self-reference):

{
  "status": "error",
  "operation": "link",
  "code": "VALIDATION_ERROR",
  "message": "Cannot link issue to itself",
  "details": "issue_id and related_issue_id must be different"
}

Error (invalid relationship):

{
  "status": "error",
  "operation": "link",
  "code": "VALIDATION_ERROR",
  "message": "Invalid relationship_type: invalid_type",
  "details": "Must be one of: relates_to, blocks, blocked_by, duplicates"
}

Self-Reference

• issue_id equals related_issue_id
• Return error with code "VALIDATION_ERROR"

Invalid Relationship Type

• relationship_type not in allowed list
• Return error with valid options

Issue Not Found

• CLI returns error code "NOT_FOUND"
• Return error with message

Authentication Failed

• CLI returns error code "AUTH_FAILED"
• Return error suggesting checking token

CLI Not Found

• Check if fractary command exists
• Return error suggesting: npm install -g @fractary/cli

Start/End Message Format

Start Message

🎯 STARTING: Issue Linker
Operation: link
Source Issue: #123
Related Issue: #456
Relationship: blocks
───────────────────────────────────────

End Message (Success)

✅ COMPLETED: Issue Linker
Linked: #123 → #456 (blocks)
Method: Comment references
Platform: github
───────────────────────────────────────
Next: Relationship is now visible in both issues

Relationship Types Explained

relates_to (Bidirectional)

General relationship without implied ordering or blocking.

• Comment on #123: "Related to #456"
• Comment on #456: "Related to #123"

blocks (Directional with inverse)

Source issue must be completed before target can start.

• Comment on #123: "Blocks #456"
• Comment on #456: "Blocked by #123"

blocked_by (Directional with inverse)

Source issue cannot start until target is completed.

• Comment on #123: "Blocked by #456"
• Comment on #456: "Blocks #123"

duplicates (Directional only)

Source issue is a duplicate of target.

• Comment on #123: "Duplicate of #456"
• (No inverse comment on target)

Dependencies

• @fractary/cli >= 0.3.0 - Fractary CLI with comment create
• jq - JSON parsing
• work-manager agent for routing

Migration Notes

Previous implementation: Used handler scripts (handler-work-tracker-github, etc.) Current implementation: Uses Fractary CLI directly (fractary work comment create)

The CLI handles:

• Platform detection from configuration
• Authentication via environment variables
• API calls to GitHub/Jira/Linear
• Response normalization

Platform Notes

GitHub

• Uses comment references (#123) as native linking not available
• Comments visible in timeline but not queryable as structured relationships
• Bidirectional relationships require comments on both issues

Jira (Future)

• Native issue links API with typed relationships
• Built-in support for blocks, relates to, duplicates

Linear (Future)

• Native relations API
• Support for blocks, related, duplicates