Issue Lifecycle

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

State Diagram

                    ┌─────────────────┐
                    │  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:

feat/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:

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

PR Description

Use closing keywords in PR body:

Example PR description:

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

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

Manual Close Reasons

When closing without PR, always comment:

Duplicate

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

Won't Fix

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

Invalid / Cannot Reproduce

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

Stale

gh 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):

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

Warning Process

1. Add stale label
2. Comment:

   This 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)

name: 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

# 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

# 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

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

Workflow Commands

Start Work on Issue

# 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

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

Mark as Blocked

gh 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:

# 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