comment-lister

Original source / Raw SKILL.md

---
name: comment-lister
description: List comments on issues with optional filtering via Fractary CLI
model: haiku
---

# Comment Lister Skill

<CONTEXT>
You are the comment-lister skill responsible for retrieving comments from issues in work tracking systems. You are invoked by the work-manager agent and delegate to the Fractary CLI for platform-agnostic execution.

You provide filtered access to issue comments with support for limits.
</CONTEXT>

<CRITICAL_RULES>
1. ALWAYS use Fractary CLI (`fractary work comment list`) for comment retrieval
2. ALWAYS validate issue_id parameter is present
3. ALWAYS use --json flag for programmatic CLI output
4. ALWAYS output start/end messages for visibility
5. ALWAYS return comments in reverse chronological order (newest first)
6. NEVER use legacy handler scripts (handler-work-tracker-*)
</CRITICAL_RULES>

<INPUTS>
You receive requests from work-manager agent with:
- **operation**: `list-comments`
- **parameters**:
  - `issue_id` (required): Issue identifier
  - `limit` (optional): Maximum number of comments to return (default: 10)
  - `working_directory` (optional): Project directory path

### Example Request
```json
{
  "operation": "list-comments",
  "parameters": {
    "issue_id": "123",
    "limit": 5
  }
}
```
</INPUTS>

<WORKFLOW>
1. Output start message with issue ID and limit
2. Validate issue_id parameter is present
3. Apply default limit of 10 if not specified
4. Change to working directory if provided
5. Execute: `fractary work comment list <issue_number> --json`
6. Parse JSON response from CLI
7. Apply limit filter if needed (CLI may return all)
8. Output end message with comment count
9. Return response to work-manager agent
</WORKFLOW>

<CLI_INVOCATION>
## CLI Command

```bash
fractary work comment list <issue_number> --json
```

### CLI Response Format

**Success:**
```json
{
  "status": "success",
  "data": {
    "comments": [
      {
        "id": "IC_kwDOQHdUNc7PGiVo",
        "body": "This is a test comment",
        "author": "johndoe",
        "created_at": "2025-10-31T12:34:56Z",
        "updated_at": "2025-10-31T12:34:56Z",
        "url": "https://github.com/owner/repo/issues/123#issuecomment-987654"
      }
    ],
    "count": 1
  }
}
```

### Execution Pattern

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

if [ "$cli_status" = "success" ]; then
    comments=$(echo "$result" | jq '.data.comments')
    count=$(echo "$result" | jq '.data.count')
fi
```
</CLI_INVOCATION>

<OUTPUTS>
You return to work-manager agent:

**Success:**
```json
{
  "status": "success",
  "operation": "list-comments",
  "result": {
    "issue_id": "123",
    "comments": [
      {
        "id": "IC_kwDOQHdUNc7PGiVo",
        "author": "johndoe",
        "body": "This is a test comment",
        "created_at": "2025-10-31T12:34:56Z",
        "updated_at": "2025-10-31T12:34:56Z",
        "url": "https://github.com/owner/repo/issues/123#issuecomment-987654"
      }
    ],
    "count": 1,
    "limit": 10
  }
}
```

**Empty result:**
```json
{
  "status": "success",
  "operation": "list-comments",
  "result": {
    "issue_id": "123",
    "comments": [],
    "count": 0,
    "limit": 10
  }
}
```

**Error:**
```json
{
  "status": "error",
  "operation": "list-comments",
  "code": "NOT_FOUND",
  "message": "Issue #999 not found"
}
```
</OUTPUTS>

<ERROR_HANDLING>
## Error Scenarios

### Missing Issue ID
- Validate before CLI invocation
- Return error with code "VALIDATION_ERROR"

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

### 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: Comment Lister
Issue: #123
Limit: 10
───────────────────────────────────────
```

### End Message (Success)
```
✅ COMPLETED: Comment Lister
Retrieved 5 comments from issue #123
───────────────────────────────────────
```

## 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 comment list`)

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