# Skill: Issues

Manage GitHub issues — create, list, search, view, comment, close, and triage.

## Commands Reference

### List Issues

```bash
# List open issues (default)
gh issue list --json number,title,state,labels,assignees,createdAt --limit 30

# Filter by state
gh issue list --state closed --json number,title,closedAt --limit 20
gh issue list --state all --json number,title,state --limit 50

# Filter by label
gh issue list --label bug --json number,title,labels
gh issue list --label "priority:high" --label "bug" --json number,title

# Filter by assignee
gh issue list --assignee "@me" --json number,title,state
gh issue list --assignee "username" --json number,title

# Filter by milestone
gh issue list --milestone "v2.0" --json number,title

# Filter by author
gh issue list --author "username" --json number,title

# Combine filters
gh issue list --label bug --assignee "@me" --state open --limit 10 --json number,title,labels
```

### Search Issues

Use `gh issue list --search` for advanced queries (GitHub search syntax):

```bash
# Text search
gh issue list --search "login error" --json number,title,state

# Search with qualifiers
gh issue list --search "is:open label:bug sort:created-desc" --json number,title,createdAt
gh issue list --search "is:open no:assignee label:good-first-issue" --json number,title
gh issue list --search "mentions:@me is:open" --json number,title

# Search across repos (use gh api for cross-repo search)
gh api search/issues -f q="org:myorg is:issue is:open label:bug" --jq '.items[] | "\(.repository_url | split("/") | .[-1]) #\(.number): \(.title)"'
```

### View an Issue

```bash
# Full detail
gh issue view 42 --json number,title,body,state,labels,assignees,comments,milestone,createdAt,author

# Just the body
gh issue view 42 --json body --jq '.body'

# Comments only
gh issue view 42 --json comments --jq '.comments[] | "\(.author.login) (\(.createdAt)): \(.body)"'

# Check if issue is open
gh issue view 42 --json state --jq '.state'
```

### Create an Issue

```bash
# Basic issue
gh issue create --title "Bug: login page crashes on empty password" --body "## Steps to reproduce
1. Go to /login
2. Leave password empty
3. Click submit

## Expected
Validation error shown

## Actual
Page crashes with 500 error"

# With labels and assignee
gh issue create \
  --title "Add dark mode support" \
  --body "Users have requested dark mode. See #12 for discussion." \
  --label "enhancement" \
  --label "ui" \
  --assignee "@me"

# With milestone
gh issue create \
  --title "Update dependencies" \
  --body "Quarterly dependency update" \
  --milestone "v2.1"

# From a file
gh issue create --title "Release checklist" --body-file ./ISSUE_TEMPLATE.md

# In a different repo
gh issue create -R owner/repo --title "Cross-repo issue" --body "Details here"
```

### Comment on an Issue

```bash
# Add a comment
gh issue comment 42 --body "I can reproduce this on macOS 14.2 with Node 20."

# Add a comment from a file
gh issue comment 42 --body-file ./analysis.md

# Comment on issue in another repo
gh issue comment 42 -R owner/repo --body "Linked to our internal tracker."
```

### Edit an Issue

```bash
# Update title
gh issue edit 42 --title "Bug: login crashes on empty password (confirmed)"

# Update body
gh issue edit 42 --body "Updated description with more details..."

# Add labels
gh issue edit 42 --add-label "confirmed,priority:high"

# Remove labels
gh issue edit 42 --remove-label "needs-triage"

# Change assignees
gh issue edit 42 --add-assignee "developer1"
gh issue edit 42 --remove-assignee "developer2"

# Set milestone
gh issue edit 42 --milestone "v2.0"

# Multiple edits at once
gh issue edit 42 \
  --title "Updated title" \
  --add-label "in-progress" \
  --remove-label "needs-triage" \
  --add-assignee "@me"
```

### Close / Reopen Issues

```bash
# Close an issue
gh issue close 42

# Close with a reason
gh issue close 42 --reason "not planned"
gh issue close 42 --reason "completed"

# Close with a comment
gh issue close 42 --comment "Fixed in #55"

# Reopen
gh issue reopen 42
```

### Pin / Unpin Issues

```bash
gh issue pin 42
gh issue unpin 42
```

### Transfer an Issue

```bash
gh issue transfer 42 owner/other-repo
```

### Lock / Unlock

```bash
gh issue lock 42 --reason "resolved"
gh issue unlock 42
```

## Workflows

### Triage Workflow

Review and categorize new issues:

```bash
# 1. Find untriaged issues
gh issue list --search "is:open no:label -label:triaged" --json number,title,createdAt,author --limit 20

# 2. View each issue
gh issue view <number> --json number,title,body,author

# 3. Categorize (add labels, assign, set milestone)
gh issue edit <number> --add-label "bug,priority:medium,triaged" --add-assignee "developer1"

# 4. If needs more info
gh issue comment <number> --body "Thanks for reporting. Could you provide your OS version and browser?"
gh issue edit <number> --add-label "needs-info"
```

### Bug Report Workflow

Create a well-structured bug report:

```bash
gh issue create \
  --title "Bug: <short description>" \
  --body "$(cat <<'EOF'
## Environment
- OS: 
- Version: 
- Browser: 

## Steps to Reproduce
1. 
2. 
3. 

## Expected Behavior


## Actual Behavior


## Screenshots / Logs

EOF
)" \
  --label "bug,needs-triage"
```

### Bulk Close Stale Issues

```bash
# Find stale issues (no activity in 90 days)
gh issue list --search "is:open updated:<$(date -d '90 days ago' +%Y-%m-%d)" --json number --jq '.[].number' | while read -r num; do
  gh issue close "$num" --comment "Closing due to inactivity. Reopen if still relevant."
done
```

### Link Issues to PRs

Issues are automatically linked when a PR body contains `Closes #42`, `Fixes #42`, or `Resolves #42`. You can also manually reference:

```bash
gh issue comment 42 --body "Being addressed in #55 (PR)"
```

## Available JSON Fields

Use these with `--json`:

`assignees`, `author`, `body`, `closed`, `closedAt`, `comments`, `createdAt`, `id`, `labels`, `milestone`, `number`, `projectCards`, `reactionGroups`, `state`, `title`, `updatedAt`, `url`

## Tips

- Use `--search` with GitHub search syntax for complex queries — it's more powerful than the filter flags.
- Always include `--json` fields you actually need; requesting all fields is slower.
- For bulk operations, pipe `--jq '.[].number'` into a while loop.
- Use `--body-file` for long issue bodies to avoid shell quoting issues.
- The `@me` shorthand works for `--assignee` and `--author` filters.