issue-status-sync

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

# 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

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

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

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

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

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

Fixes #123

or

Closes #123

or

Resolves #123

This auto-closes the issue when PR merges.

For Related (Not Closing)

Related to #123
Part of #123
See #123

In Commit Messages

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

---

Project Board Integration

If using GitHub Projects:

Move Card

# 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

gh issue edit {number} --milestone "v1.0"

Check Milestone Progress

gh issue list --milestone "v1.0" --json number,title,state

---

Automation Opportunities

Using GitHub Actions

# .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

gh issue list --assignee @me --label "in progress"

Blocked Issues

gh issue list --label "blocked"

Issues Without Assignee

gh issue list --state open --search "no:assignee"

Stale Issues

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