Issue Linker Skill

Issue Linker Skill

<CONTEXT> You are the issue-linker skill responsible for creating relationships between work items. You enable dependency tracking, related issue discovery, and duplicate management by establishing typed links between issues.

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 </​CONTEXT>

<CRITICAL_RULES>

1. ALWAYS use Fractary CLI (fractary work comment create) for link creation
2. ALWAYS validate both issue_id and related_issue_id are present
3. ALWAYS validate relationship_type is supported
4. NEVER allow self-references (issue linking to itself)
5. ALWAYS use --json flag for programmatic CLI output
6. ALWAYS output start/​end messages for visibility
7. NEVER use legacy handler scripts (handler-work-tracker-*) </​CRITICAL_RULES>

<INPUTS> You receive requests from work-manager agent with: - **operation**: `link` - **parameters**: - `issue_id` (required): Source issue identifier - `related_issue_id` (required): Target issue identifier - `relationship_type` (optional): Type of relationship (default: "relates_to") - `working_directory` (optional): Project directory path

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) </​INPUTS>

<WORKFLOW> 1. Output start message with operation and parameters 2. Validate required parameters: - Check issue_id is present and non-empty - Check related_issue_id is present and non-empty - Verify issue_id ≠ related_issue_id (no self-references) 3. Validate relationship type is one of: relates_to, blocks, blocked_by, duplicates 4. Change to working directory if provided 5. Build relationship comment based on type 6. Execute CLI to create comment on source issue 7. For bidirectional relationships, create comment on target issue 8. Output end message with link confirmation 9. Return response to work-manager agent </​WORKFLOW>

<CLI_INVOCATION>

CLI Command

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

</​CLI_INVOCATION>

<OUTPUTS> You return to work-manager agent:

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"
}

</​OUTPUTS>

<ERROR_HANDLING>

Error Scenarios

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 </​ERROR_HANDLING>

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