issue-status-sync

What this skill does

# GitHub Issue Status Sync Skill

This skill provides patterns for keeping GitHub issues synchronized with actual development progress.

## GitHub Issue Status Model

Unlike Jira, GitHub issues have simple states:
- **Open**: Active, needs work
- **Closed**: Complete or won't fix

Status is conveyed through:
- Labels (in progress, blocked, etc.)
- Milestones
- Project board columns
- Comments

---

## Status Labels

### Recommended Label Set

**Workflow:**
- `needs-triage` - Needs initial review
- `needs-info` - Waiting for reporter
- `in progress` - Being worked on
- `blocked` - Cannot proceed
- `ready for review` - PR ready
- `ready for merge` - Approved, waiting merge

**Type:**
- `bug`
- `enhancement`
- `documentation`
- `chore`

**Priority:**
- `priority: critical`
- `priority: high`
- `priority: medium`
- `priority: low`

### Status Transitions via Labels

```bash
# Starting work
gh issue edit {number} --add-label "in progress" --remove-label "needs-triage"

# Blocked
gh issue edit {number} --add-label "blocked"

# Ready for review
gh issue edit {number} --add-label "ready for review" --remove-label "in progress"

# Complete
gh issue close {number} --comment "Completed in PR #456"
```

---

## Progress Updates

### Starting Work

```bash
gh issue edit {number} --add-assignee @me --add-label "in progress"
gh issue comment {number} --body "$(cat <<'EOF'
Starting work on this issue.

**Approach:**
- [Brief description]

**Branch:** `feature/{number}-description`

**ETA:** [Rough estimate]
EOF
)"
```

### Progress Update

```bash
gh issue comment {number} --body "$(cat <<'EOF'
**Progress Update**

**Completed:**
- [What's done]

**In Progress:**
- [Current work]

**Next:**
- [What's planned]

**Blockers:** None / [Description]
EOF
)"
```

### Blocked

```bash
gh issue edit {number} --add-label "blocked"
gh issue comment {number} --body "$(cat <<'EOF'
**Blocked**

**Reason:** [Clear explanation]
**Blocked by:** #123 / [External factor]
**Action needed:** [What would unblock]
**Impact:** [What can't proceed]
EOF
)"
```

### Unblocked

```bash
gh issue edit {number} --remove-label "blocked"
gh issue comment {number} --body "$(cat <<'EOF'
**Unblocked**

**Resolution:** [How it was resolved]
**Next steps:** [Resuming work]
EOF
)"
```

### Completing Work

```bash
gh issue comment {number} --body "$(cat <<'EOF'
**Completed**

**PR:** #456
**Changes:**
- [Summary of changes]

**Testing:**
- [How it was tested]

Ready for review.
EOF
)"
gh issue edit {number} --add-label "ready for review" --remove-label "in progress"
```

---

## Linking PRs to Issues

### In PR Description

```markdown
Fixes #123

or

Closes #123

or

Resolves #123
```

This auto-closes the issue when PR merges.

### For Related (Not Closing)

```markdown
Related to #123
Part of #123
See #123
```

### In Commit Messages

```bash
git commit -m "feat(auth): add password reset (#123)"
```

---

## Project Board Integration

If using GitHub Projects:

### Move Card
```bash
# List project columns
gh api repos/{owner}/{repo}/projects/{project_id}/columns

# Move issue card
gh api projects/columns/cards/{card_id}/moves \
  -f position=top \
  -f column_id={column_id}
```

### Automated Moves

Configure in project settings:
- New issues → "To Do"
- Issues with "in progress" label → "In Progress"
- Closed issues → "Done"

---

## Milestone Tracking

### Assign to Milestone
```bash
gh issue edit {number} --milestone "v1.0"
```

### Check Milestone Progress
```bash
gh issue list --milestone "v1.0" --json number,title,state
```

---

## Automation Opportunities

### Using GitHub Actions

```yaml
# .github/workflows/issue-management.yml
name: Issue Management

on:
  issues:
    types: [opened, closed]
  pull_request:
    types: [opened, merged]

jobs:
  manage:
    runs-on: ubuntu-latest
    steps:
      - name: Add triage label to new issues
        if: github.event_name == 'issues' && github.event.action == 'opened'
        run: gh issue edit ${{ github.event.issue.number }} --add-label "needs-triage"
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

---

## Status Check Commands

### My In-Progress Issues
```bash
gh issue list --assignee @me --label "in progress"
```

### Blocked Issues
```bash
gh issue list --label "blocked"
```

### Issues Without Assignee
```bash
gh issue list --state open --search "no:assignee"
```

### Stale Issues
```bash
gh issue list --state open --search "updated:<2024-01-01"
```

---

## Best Practices

### Do:
- Update status promptly
- Add context with changes
- Link related issues and PRs
- Use consistent labels
- Close with resolution summary

### Don't:
- Leave issues "in progress" when blocked
- Forget to assign yourself
- Close without explanation
- Mix up similar issues
- Ignore stale issues

---

## Quick Reference

| Event | Label Changes | Comment |
|-------|---------------|---------|
| Starting | +in progress, -needs-triage | Approach + branch |
| Blocked | +blocked | Reason + action needed |
| Unblocked | -blocked | Resolution |
| PR Ready | +ready for review, -in progress | PR link |
| Complete | Close issue | Summary of changes |