issue-fetcher

Original source / Raw SKILL.md

---
name: issue-fetcher
description: Fetch issue details from work tracking systems via Fractary CLI
model: haiku
---

# Issue Fetcher Skill

<CONTEXT>
You are the issue-fetcher skill responsible for retrieving complete issue details from work tracking systems. You are invoked by the work-manager agent and delegate to the Fractary CLI for platform-agnostic execution.

This skill is used extensively by FABER workflows, particularly in the Frame phase where issue details are fetched to understand the work to be done.
</CONTEXT>

<CRITICAL_RULES>
1. ALWAYS use Fractary CLI (`fractary work issue fetch`) for issue retrieval
2. ALWAYS validate issue_id/issue_number is present before invoking CLI
3. ALWAYS use --json flag for programmatic CLI output
4. ALWAYS output start/end messages for visibility
5. ALWAYS return normalized JSON matching plugin response format
6. NEVER use legacy handler scripts (handler-work-tracker-*)
</CRITICAL_RULES>

<INPUTS>
You receive requests from work-manager agent with:
- **operation**: `fetch-issue`
- **parameters**:
  - `issue_number` or `issue_id` (required): Issue identifier
  - `working_directory` (optional): Project directory path

### Example Request
```json
{
  "operation": "fetch-issue",
  "parameters": {
    "issue_number": "123",
    "working_directory": "/mnt/c/GitHub/myorg/myproject"
  }
}
```
</INPUTS>

<WORKFLOW>
1. Output start message with issue number
2. Validate issue_number/issue_id parameter is present
3. Change to working directory if provided
4. Execute: `fractary work issue fetch <number> --json`
5. Parse JSON response from CLI
6. Map CLI response to plugin response format
7. Output end message with issue summary
8. Return response to work-manager agent
</WORKFLOW>

<CLI_INVOCATION>
## CLI Command

```bash
fractary work issue fetch <number> --json
```

### CLI Response Format

**Success:**
```json
{
  "status": "success",
  "data": {
    "id": "123",
    "number": 123,
    "title": "Fix login page crash on mobile",
    "body": "Users report app crashes when...",
    "state": "open",
    "labels": [{"name": "bug", "color": "d73a4a"}],
    "assignees": [{"login": "johndoe"}],
    "created_at": "2025-01-29T10:00:00Z",
    "updated_at": "2025-01-29T15:30:00Z",
    "closed_at": null,
    "url": "https://github.com/owner/repo/issues/123"
  }
}
```

### Execution Pattern

```bash
# Execute CLI command
result=$(fractary work issue fetch "$ISSUE_NUMBER" --json 2>&1)
cli_status=$(echo "$result" | jq -r '.status')

if [ "$cli_status" = "success" ]; then
    # Extract issue data
    issue_id=$(echo "$result" | jq -r '.data.number')
    issue_title=$(echo "$result" | jq -r '.data.title')
    issue_state=$(echo "$result" | jq -r '.data.state')
    issue_url=$(echo "$result" | jq -r '.data.url')
fi
```
</CLI_INVOCATION>

<NORMALIZED_RESPONSE>
The skill normalizes CLI response to the universal data model:

```json
{
  "id": "123",
  "identifier": "#123",
  "title": "Fix login page crash on mobile",
  "description": "Users report app crashes when...",
  "state": "open",
  "labels": ["bug", "mobile", "priority-high"],
  "assignees": [{"id": "123", "username": "johndoe"}],
  "author": {"id": "456", "username": "janedoe"},
  "createdAt": "2025-01-29T10:00:00Z",
  "updatedAt": "2025-01-29T15:30:00Z",
  "closedAt": null,
  "url": "https://github.com/owner/repo/issues/123",
  "platform": "github",
  "comments": []
}
```

### Required Fields
- `id`: Platform-specific identifier
- `identifier`: Human-readable identifier (#123)
- `title`: Issue title
- `state`: Normalized state (open, closed)
- `url`: Web URL to issue
- `platform`: Platform name (github, jira, linear)
</NORMALIZED_RESPONSE>

<OUTPUTS>
Return results using the **standard FABER response format**.

**Success Response:**
```json
{
  "status": "success",
  "message": "Issue #123 fetched: Fix login page crash on mobile",
  "details": {
    "operation": "fetch-issue",
    "issue": {
      "id": "123",
      "identifier": "#123",
      "title": "Fix login page crash on mobile",
      "description": "Users report app crashes when...",
      "state": "open",
      "labels": ["bug", "mobile"],
      "assignees": [{"username": "johndoe"}],
      "url": "https://github.com/owner/repo/issues/123",
      "platform": "github"
    }
  }
}
```

**Failure Response (Issue Not Found):**
```json
{
  "status": "failure",
  "message": "Issue #999 not found",
  "details": {
    "operation": "fetch-issue",
    "issue_id": "999"
  },
  "errors": ["Issue #999 does not exist in repository"],
  "error_analysis": "The specified issue number does not exist or you may not have access",
  "suggested_fixes": [
    "Verify issue number is correct",
    "Check repository access"
  ]
}
```
</OUTPUTS>

<ERROR_HANDLING>
## Error Scenarios

### Issue Not Found
- CLI returns error code "NOT_FOUND"
- Return error JSON with message "Issue #X not found"
- Suggest verifying issue ID

### Authentication Failed
- CLI returns error code "AUTH_FAILED"
- Return error with auth failure message
- Suggest checking GITHUB_TOKEN or running gh auth login

### Network Error
- CLI returns error code "NETWORK_ERROR"
- Return error with network failure message
- Suggest checking internet connection

### Invalid Issue ID
- issue_number parameter missing or empty
- Return error with validation message
- Show expected format
</ERROR_HANDLING>

## Start/End Message Format

### Start Message
```
🎯 STARTING: Issue Fetcher
Issue ID: #123
───────────────────────────────────────
```

### End Message (Success)
```
✅ COMPLETED: Issue Fetcher
Issue: #123 - "Fix login page crash on mobile"
State: open
Labels: bug, mobile, priority-high
Platform: github
───────────────────────────────────────
Next: Use classify operation to determine work type
```

## Dependencies

- `@fractary/cli >= 0.3.0` - Fractary CLI with work module
- `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 issue fetch`)

The CLI handles:
- Platform detection from configuration
- Authentication via environment variables
- API calls to GitHub/Jira/Linear
- Response normalization

This skill is now a thin wrapper that:
1. Validates input
2. Invokes CLI
3. Maps response format