# GitHub Issue Management Command

You are helping the user create, update, and manage GitHub issues following Sngular's project management best practices.

## Instructions

1. **Determine the action**:
   - Create a new issue
   - Update an existing issue
   - Close an issue
   - List issues with filters
   - Link related issues
   - Bulk operations on issues

2. **Verify GitHub repository**:
   - Check if in a git repository
   - Verify GitHub remote is configured
   - Confirm user has `gh` CLI installed and authenticated

3. **Gather issue details**:
   - Title (clear, concise, action-oriented)
   - Description (problem statement, context, impact)
   - Labels (type, priority, component, status)
   - Assignees (who should work on this)
   - Milestone (which release or sprint)
   - Projects (which project board)

## Issue Creation

### Issue Template Structure

```markdown
## Problem Statement
Clear description of the issue, bug, or feature request.

## Current Behavior
What is happening now? (for bugs)

## Expected Behavior
What should happen instead?

## Steps to Reproduce
(For bugs)
1. Step 1
2. Step 2
3. Step 3

## Proposed Solution
(For features)
High-level approach to implementing this feature.

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3

## Technical Details
- Affected components:
- Dependencies:
- Estimated effort:

## Additional Context
Screenshots, logs, or relevant information.

## Related Issues
- Relates to #123
- Blocks #456
- Blocked by #789
```

### Issue Types & Labels

**Type Labels**:
- `bug` - Something isn't working
- `feature` - New feature or enhancement
- `documentation` - Documentation improvements
- `refactor` - Code refactoring
- `performance` - Performance improvements
- `security` - Security-related issues
- `tech-debt` - Technical debt

**Priority Labels**:
- `priority: critical` - Urgent, blocking work
- `priority: high` - Important, should be done soon
- `priority: medium` - Normal priority
- `priority: low` - Nice to have

**Status Labels**:
- `status: triage` - Needs initial review
- `status: ready` - Ready for development
- `status: in-progress` - Currently being worked on
- `status: review` - In code review
- `status: blocked` - Blocked by dependencies
- `status: on-hold` - Paused temporarily

**Component Labels**:
- `frontend` - UI/UX related
- `backend` - Server-side code
- `database` - Database changes
- `devops` - Infrastructure/deployment
- `api` - API changes

## GitHub CLI Commands

### Creating Issues

```bash
# Create basic issue
gh issue create --title "Issue title" --body "Issue description"

# Create issue with labels and assignee
gh issue create \
  --title "Add user authentication" \
  --body "$(cat issue-template.md)" \
  --label "feature,backend,priority: high" \
  --assignee username

# Create issue with milestone
gh issue create \
  --title "Fix login bug" \
  --body "Description" \
  --label "bug,priority: critical" \
  --milestone "Sprint 24"

# Create issue and assign to project
gh issue create \
  --title "Implement dashboard" \
  --body "Description" \
  --label "feature" \
  --project "Q4 Roadmap"

# Interactive issue creation
gh issue create
```

### Viewing Issues

```bash
# List all open issues
gh issue list

# List issues with specific label
gh issue list --label "bug"

# List issues assigned to user
gh issue list --assignee @me

# List issues in specific state
gh issue list --state closed

# List with custom columns
gh issue list --json number,title,labels,state

# View specific issue
gh issue view 123

# View issue in browser
gh issue view 123 --web
```

### Updating Issues

```bash
# Edit issue title
gh issue edit 123 --title "New title"

# Add labels
gh issue edit 123 --add-label "bug,priority: high"

# Remove labels
gh issue edit 123 --remove-label "priority: low"

# Add assignee
gh issue edit 123 --add-assignee username

# Remove assignee
gh issue edit 123 --remove-assignee username

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

# Update body
gh issue edit 123 --body "New description"

# Add comment
gh issue comment 123 --body "This is a comment"

# Close issue
gh issue close 123

# Close with comment
gh issue close 123 --comment "Fixed in PR #456"

# Reopen issue
gh issue reopen 123
```

### Linking Issues

```bash
# Reference in comment
gh issue comment 123 --body "Related to #456"

# Link as blocking
gh issue comment 123 --body "Blocks #456"

# Link as blocked by
gh issue comment 123 --body "Blocked by #789"

# Link to PR
gh issue comment 123 --body "Fixed in PR #100"
```

### Bulk Operations

```bash
# Close multiple issues
gh issue list --label "wontfix" --json number --jq '.[].number' | \
  xargs -I {} gh issue close {}

# Add label to multiple issues
gh issue list --search "authentication" --json number --jq '.[].number' | \
  xargs -I {} gh issue edit {} --add-label "security"

# Assign all unassigned bugs
gh issue list --label "bug" --json number,assignees --jq '.[] | select(.assignees | length == 0) | .number' | \
  xargs -I {} gh issue edit {} --add-assignee username
```

## Issue Templates

### Bug Report Template

```markdown
## Bug Description
Brief description of the bug.

## Environment
- OS: [e.g., macOS 14.0]
- Browser: [e.g., Chrome 120]
- Version: [e.g., 2.0.1]

## Steps to Reproduce
1. Go to '...'
2. Click on '...'
3. Scroll down to '...'
4. See error

## Expected Behavior
What you expected to happen.

## Actual Behavior
What actually happened.

## Screenshots/Logs
If applicable, add screenshots or logs.

## Possible Solution
(Optional) Suggest a fix or reason for the bug.

## Additional Context
Any other context about the problem.
```

### Feature Request Template

```markdown
## Feature Description
Clear description of the feature you'd like to see.

## Problem Statement
What problem does this feature solve?

## Proposed Solution
How should this feature work?

## Alternatives Considered
What other approaches did you consider?

## User Stories
- As a [user type], I want to [action], so that [benefit]

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2

## Technical Considerations
- Dependencies:
- Performance impact:
- Security implications:
- Breaking changes:

## Priority & Impact
- Priority: [High/Medium/Low]
- User impact: [High/Medium/Low]
- Implementation effort: [Large/Medium/Small]
```

## Best Practices

### Writing Good Issue Titles

✅ **Good**:
- "Add CSV export for user data"
- "Fix pagination bug on dashboard"
- "Improve API response time for /users endpoint"
- "Update authentication flow to support OAuth"

❌ **Bad**:
- "Bug" (not descriptive)
- "Feature request" (too vague)
- "This doesn't work" (no context)
- "URGENT FIX ASAP!!!" (not professional)

### Title Format
- **Bugs**: "Fix [issue] in [component]"
- **Features**: "Add [feature] to [component]"
- **Improvements**: "Improve [aspect] of [component]"
- **Refactoring**: "Refactor [component] to [goal]"

### Writing Good Descriptions

1. **Be specific**: Include exact error messages, versions, conditions
2. **Provide context**: Explain why this matters, who it affects
3. **Include steps**: For bugs, clear reproduction steps
4. **Add visuals**: Screenshots, diagrams, recordings when helpful
5. **Link related work**: Reference related issues, PRs, docs
6. **Set expectations**: Clarify scope, acceptance criteria

### Label Strategy

- Use consistent label taxonomy across the project
- Limit to 3-5 labels per issue for clarity
- Always include: type, priority, and component labels
- Use status labels to track progress
- Create custom labels for recurring themes

### Assigning Issues

- Assign when someone actively works on it
- Don't assign too far in advance
- One primary assignee, others as collaborators
- Unassign if work is paused or blocked

## Workflow Examples

### Example 1: Create Bug Report

```bash
# User reports: "Login page is broken on mobile"

gh issue create \
  --title "Fix login page layout on mobile devices" \
  --body "$(cat <<'EOF'
## Bug Description
The login form is not responsive on mobile devices below 768px width.

## Environment
- Device: iPhone 14
- OS: iOS 17.0
- Browser: Safari

## Steps to Reproduce
1. Open application on mobile device
2. Navigate to /login
3. Observe layout issues

## Expected Behavior
Login form should be centered and fully visible on mobile.

## Actual Behavior
Form elements overflow screen, submit button is cut off.

## Screenshots
[Attach screenshots]

## Acceptance Criteria
- [ ] Form is responsive on screens < 768px
- [ ] All elements visible without scrolling
- [ ] Touch targets are at least 44x44px
- [ ] Tested on iOS Safari and Android Chrome
EOF
)" \
  --label "bug,frontend,priority: high" \
  --assignee frontend-team
```

### Example 2: Feature Request with Requirements

```bash
gh issue create \
  --title "Add user profile settings page" \
  --body "$(cat ./docs/requirements/user-profile.md)" \
  --label "feature,frontend,backend" \
  --milestone "v2.0" \
  --project "Q4 Features"
```

### Example 3: Link Related Issues

```bash
# This PR fixes issue #123 and is related to #124
gh issue comment 123 --body "Fixed in PR #200"
gh issue close 123
gh issue comment 124 --body "Implementation approach discussed in #123"
```

### Example 4: Triage Issues

```bash
# Review new issues
gh issue list --label "status: triage"

# Add priority and status
gh issue edit 123 --add-label "priority: high,status: ready" --remove-label "status: triage"

# Assign to team member
gh issue edit 123 --add-assignee developer1
```

## Integration with Project Boards

```bash
# List projects
gh project list

# View project
gh project view 1

# Add issue to project
gh project item-add 1 --url https://github.com/owner/repo/issues/123

# Move issue on board
gh project item-edit --project-id 1 --id ITEM_ID --field-id STATUS_FIELD_ID --value "In Progress"
```

## Advanced Filtering

```bash
# Issues created in last week
gh issue list --search "created:>=$(date -v-7d +%Y-%m-%d)"

# High priority unassigned bugs
gh issue list --label "bug,priority: high" --search "no:assignee"

# Issues mentioning "authentication"
gh issue list --search "authentication in:title,body"

# Issues assigned to me that are in progress
gh issue list --assignee @me --label "status: in-progress"
```

## Questions to Ask

Before creating or updating an issue:
1. "What type of issue is this? (bug, feature, improvement)"
2. "What is the clear, actionable title?"
3. "Do you have specific details like steps to reproduce or requirements?"
4. "What priority should this have?"
5. "Should this be assigned to anyone?"
6. "Should this be added to a milestone or project?"
7. "Are there related issues we should link to?"

Ask the user: "What would you like to do with GitHub issues?"