# Issue Status Sync

> Patterns for keeping GitHub issue status synchronized with development progress. Use when this capability is needed.

- Skill: `tomevault-io/issue-status-sync` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/issue-status-sync`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/issue-status-sync/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/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

```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 |

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/the-answerai) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->