issue-linker

Original source / Raw SKILL.md

---
name: issue-linker
description: Create relationships between issues via comment references
model: haiku
---

# 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
```json
{
  "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:

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

### Comment Templates by Relationship Type

| Type | Source Comment | Target Comment (if bidirectional) |
|------|----------------|-----------------------------------|
| `relates_to` | "Related to #456" | "Related to #123" |
| `blocks` | "Blocks #456" | "Blocked by #123" |
| `blocked_by` | "Blocked by #456" | "Blocks #123" |
| `duplicates` | "Duplicate of #456" | (none) |

### Execution Pattern

```bash
# 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:**
```json
{
  "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):**
```json
{
  "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):**
```json
{
  "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