---

name: gh-issue-lifecycle description: GitHub issue state machine and code integration patterns. Covers state transitions (needs-triage → accepted → in-progress → completed), branch naming (feat/123-desc), PR linking (Closes #123), close reasons (duplicate/won't fix/invalid/stale), and bulk operations.

Issue Lifecycle

State machine for GitHub issues and how they connect to code.

State Diagram

Copy                    ┌─────────────────┐
                    │  needs-triage   │ ← New issue created
                    └────────┬────────┘
                             │ triage
                    ┌────────▼────────┐
        ┌───────────│    accepted     │ ← In backlog
        │           └────────┬────────┘
        │                    │ start work
        │           ┌────────▼────────┐
        │    ┌──────│  in-progress    │ ← Active development
        │    │      └────────┬────────┘
        │    │               │ PR merged
        │    │      ┌────────▼────────┐
        │    │      │    completed    │ ← Issue resolved
        │    │      └─────────────────┘
        │    │
        │    │ blocked
        │    │      ┌─────────────────┐
        │    └─────►│     blocked     │ ← Waiting on dependency
        │           └─────────────────┘
        │
        │ needs-info
        │           ┌─────────────────┐
        └──────────►│   needs-info    │ ← Waiting for clarification
                    └─────────────────┘

State Definitions

Open States

Closed States

Linking Issues to Code

Branch Naming

When starting work on issue #123:

Copyfeat/123-short-description    # feature
fix/123-short-description     # bug fix
chore/123-short-description   # maintenance
docs/123-short-description    # documentation
i18n/locale-code              # internationalization (e.g., i18n/zh-CN, i18n/ja-JP)
i18n/123-locale-code          # i18n with issue (e.g., i18n/42-es-MX)

Examples:

• feat/42-add-dark-mode
• fix/123-login-timeout
• chore/99-update-deps
• i18n/zh-CN - Chinese (Simplified) translations
• i18n/42-ja-JP - Japanese translations for issue #42

PR Title

Include issue number in PR title:

Copyfeat: add dark mode (#42)
fix: resolve login timeout (#123)
chore: update dependencies (#99)

PR Description

Use closing keywords in PR body:

Example PR description:

Copy## Summary
Add dark mode toggle to settings page.

Closes #42

## Changes
- Add theme context
- Create toggle component
- Update color variables

Linking Without Closing

Reference issues without auto-close:

CopyRelated to #45
See also #67
Depends on #89

Manual Close Reasons

When closing without PR, always comment:

Duplicate

Copygh issue close 123 --comment "Duplicate of #456"

Won't Fix

Copygh issue close 123 --comment "Closing as won't fix: [reason]"

Invalid / Cannot Reproduce

Copygh issue close 123 --comment "Cannot reproduce with provided steps. Please reopen with more details if issue persists."

Stale

Copygh issue close 123 --comment "Closing due to inactivity. Please reopen if still relevant."

Stale Issue Handling

Detection

Issues with no activity for N days (typically 90):

Copy# Find stale issues
gh issue list --search "updated:<$(date -v-90d +%Y-%m-%d)"

Warning Process

1. Add stale label
2. Comment:

   CopyThis issue has been inactive for 90 days.
   It will be closed in 30 days if there's no further activity.
   Please comment if this is still relevant.
   

3. Close after 30 more days if no response

Automation (GitHub Action)

Copyname: Stale Issues
on:
  schedule:
    - cron: '0 0 * * *'
jobs:
  stale:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/stale@v9
        with:
          stale-issue-message: 'This issue has been inactive for 90 days.'
          days-before-stale: 90
          days-before-close: 30
          stale-issue-label: 'stale'

Bulk Operations

Close Multiple Issues

Copy# Close all issues with label
gh issue list --label "stale" --json number --jq '.[].number' | \
  xargs -I {} gh issue close {} --comment "Closing stale issue"

Relabel Issues

Copy# Add label to all issues matching query
gh issue list --search "is:open label:bug" --json number --jq '.[].number' | \
  xargs -I {} gh issue edit {} --add-label "needs-review"

Transfer Issues

Copy# Move issue to another repo
gh issue transfer 123 owner/other-repo

Workflow Commands

Start Work on Issue

Copy# Create branch from issue
gh issue develop 123 --checkout

# Or manually
git checkout -b fix/123-description main
gh issue edit 123 --add-label "in-progress"

Complete Issue via PR

Copy# Create PR that closes issue
gh pr create --title "fix: resolve issue (#123)" --body "Closes #123"

Mark as Blocked

Copygh issue edit 123 \
  --remove-label "in-progress" \
  --add-label "blocked"
gh issue comment 123 --body "Blocked on #456"

Integration with Other Components

Full Issue Workflow

1. Create: Use gh-issue-templates to format issue
2. Triage: Use gh-issue-triage to add type/priority labels
3. Start Work: Use this skill's branch naming patterns (feat/123-desc)
4. Link to Code: Reference issue in PR using Closes #123
5. Close: Use gh-wrangler agent with this skill's close patterns
6. Cleanup: PR merge auto-closes issue via GitHub

State Transitions

This skill defines how issues move through states:

• needs-triage → Initial state (set by gh-issue-templates)
• accepted → After triage (applied by gh-wrangler using gh-issue-triage)
• in-progress → Work started (manual or via branch creation)
• blocked → Can't proceed (set manually with comment)
• Closed → Via PR merge or manual close

Branch and PR Integration

When starting work on an issue:

Copy# Branch naming from this skill
git checkout -b feat/123-description

# PR creation with linking
gh pr create --title "feat: description (#123)" --body "Closes #123"

Related

• Skill: gh-issue-templates - Creating well-formatted issues
• Skill: gh-issue-triage - Labeling and prioritization
• Agent: gh-wrangler - Interactive lifecycle management