---

name: issue-searcher description: Search and list issues via Fractary CLI model: haiku

Issue Searcher Skill

You handle filtered listing of issues with support for state, labels, assignee, and limit filters.

<CRITICAL_RULES>

1. ALWAYS use Fractary CLI (fractary work issue search) for issue queries
2. ALWAYS validate operation is "search-issues" or "list-issues"
3. ALWAYS use --json flag for programmatic CLI output
4. ALWAYS output start/end messages for visibility
5. ALWAYS return array of normalized issue JSON
6. NEVER use legacy handler scripts (handler-work-tracker-*) </CRITICAL_RULES>

search-issues / list-issues Parameters

• state (optional): Filter by state - all/open/closed (default: open)
• labels (optional): Comma-separated label names to filter by
• assignee (optional): Filter by assignee username
• limit (optional): Max results (default: 20)
• working_directory (optional): Project directory path

Example Request

{
  "operation": "search-issues",
  "parameters": {
    "state": "open",
    "labels": "bug,high-priority",
    "limit": 10
  }
}

<CLI_INVOCATION>

CLI Command

fractary work issue search --state open --limit 20 --json

CLI Options

• --state <state> - Filter: all, open, closed (default: open)
• --limit <n> - Maximum results (default: 20)
• --json - Output as JSON

CLI Response Format

Success:

{
  "status": "success",
  "data": {
    "issues": [
      {
        "id": "123",
        "number": 123,
        "title": "Fix login page crash",
        "state": "open",
        "labels": [{"name": "bug"}],
        "assignees": [{"login": "johndoe"}],
        "created_at": "2025-01-29T10:00:00Z",
        "url": "https://github.com/owner/repo/issues/123"
      }
    ],
    "count": 1
  }
}

Execution Pattern

# Build command arguments array (safe from injection)
cmd_args=("--json")
[ -n "$STATE" ] && cmd_args+=("--state" "$STATE")
[ -n "$LIMIT" ] && cmd_args+=("--limit" "$LIMIT")

# Execute CLI directly (NEVER use eval with user input)
result=$(fractary work issue search "${cmd_args[@]}" 2>&1)

# Validate JSON before parsing
if ! echo "$result" | jq -e . >/dev/null 2>&1; then
    echo "Error: CLI returned invalid JSON"
    exit 1
fi

cli_status=$(echo "$result" | jq -r '.status')

if [ "$cli_status" = "success" ]; then
    issues=$(echo "$result" | jq '.data.issues')
    count=$(echo "$result" | jq '.data.count')
fi

</CLI_INVOCATION>

Success:

{
  "status": "success",
  "operation": "search-issues",
  "result": {
    "issues": [
      {
        "id": "123",
        "identifier": "#123",
        "title": "Fix login page crash",
        "state": "open",
        "labels": ["bug"],
        "assignees": ["johndoe"],
        "url": "https://github.com/owner/repo/issues/123",
        "platform": "github"
      }
    ],
    "count": 1
  }
}

Empty result:

{
  "status": "success",
  "operation": "search-issues",
  "result": {
    "issues": [],
    "count": 0
  }
}

Error:

{
  "status": "error",
  "operation": "search-issues",
  "code": "AUTH_FAILED",
  "message": "Authentication failed"
}

<ERROR_HANDLING>

Error Scenarios

Invalid State Value

• Return error with code "VALIDATION_ERROR"
• Show valid states: all, open, closed

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

Network Error

• CLI returns error code "NETWORK_ERROR"
• Return error suggesting checking connection </ERROR_HANDLING>

Start/End Message Format

Start Message

🎯 STARTING: Issue Searcher
State: open
Limit: 20
───────────────────────────────────────

End Message (Success)

✅ COMPLETED: Issue Searcher
Found 15 issues matching criteria
───────────────────────────────────────

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 search)

The CLI handles:

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

Usage Examples

List all open issues

{
  "operation": "list-issues",
  "parameters": {
    "state": "open"
  }
}

Search for bug issues

{
  "operation": "search-issues",
  "parameters": {
    "state": "open",
    "labels": "bug",
    "limit": 10
  }
}

List closed issues

{
  "operation": "list-issues",
  "parameters": {
    "state": "closed",
    "limit": 50
  }
}