git-issue-manage

What this skill does

## When to Use This Skill

| Use this skill when... | Use the alternative when... |
|---|---|
| Transferring, pinning, locking, or bulk-editing GitHub issues | Use `github-issue-writing` to compose a single issue body well |
| Creating a development branch from an issue (`gh issue develop`) | Use `git-branch-pr-workflow` for general branch + PR design |
| Updating custom issue fields (priority, severity, custom selects) in bulk | Use `github-labels` for label-only operations on issues and PRs |
| Performing bulk operations across many issue numbers in one command | Use `git-triage` to evaluate issues and PRs by completion evidence and CI state |

## Context

- Git remotes: !`git remote -v`

Open issues are fetched during execution (requires a configured git remote).

## Parameters

Parse `$ARGUMENTS[0]` as the operation, remaining args as issue numbers and options.

| Operation | Syntax | Description |
|-----------|--------|-------------|
| `transfer` | `transfer <N> <target-repo>` | Transfer issue to another repository |
| `pin` | `pin <N...>` | Pin issues to repository (max 3) |
| `unpin` | `unpin <N...>` | Unpin issues |
| `lock` | `lock <N...> [--reason <reason>]` | Lock issue discussions |
| `unlock` | `unlock <N...>` | Unlock issue discussions |
| `develop` | `develop <N> [--branch <name>] [--checkout]` | Create branch from issue |
| `bulk` | `bulk <sub-op> <N...> [options]` | Bulk operations on multiple issues |
| `fields` | `fields <N> [--set <field>=<value>] [--list]` | Manage custom issue fields |

Lock reasons: `off-topic`, `too heated`, `resolved`, `spam`

Bulk sub-operations: `label`, `assign`, `close`, `reopen`

## When to Use

| Use this skill when... | Use X instead when... |
|------------------------|----------------------|
| Transferring issues between repos | Creating new issues (`github-issue-writing`) |
| Pinning/unpinning important issues | Implementing issue fixes (`git:issue`) |
| Locking resolved discussions | Managing sub-issues/deps (`git:issue-hierarchy`) |
| Creating dev branches from issues | Searching for issues (`github-issue-search`) |
| Bulk labeling/assigning/closing | Auto-detecting related issues (`github-issue-autodetect`) |
| Setting custom field values | |

## Execution

Execute the requested issue management operation.

### Step 1: Parse Operation and Validate

Parse the operation from `$ARGUMENTS[0]`. Validate that specified issue numbers exist:

```bash
gh issue view $N --json number,title,state 2>/dev/null
```

If any issue is not found, report it and skip that issue.

### Step 2: Execute Operation

#### Transfer

Transfer an issue to another repository within the same organization or owner.

```bash
gh issue transfer $N $TARGET_REPO
```

**Prerequisites:**
- Target repo must exist and you must have write access
- Both repos must be owned by the same user/org (or target accepts transfers)

Report the new issue URL after transfer.

#### Pin / Unpin

Pin important issues to the top of the issues list (maximum 3 pinned per repo).

```bash
# Pin
gh issue pin $N

# Unpin
gh issue unpin $N
```

If pinning would exceed the 3-pin limit, report which issues are currently pinned and ask which to unpin.

#### Lock / Unlock

Lock issue threads to prevent further comments.

```bash
# Lock with reason
gh issue lock $N --reason resolved

# Lock without reason
gh issue lock $N

# Unlock
gh issue unlock $N
```

| Reason | When to use |
|--------|-------------|
| `resolved` | Issue is fixed, no further discussion needed |
| `off-topic` | Discussion has drifted from the issue |
| `too heated` | Discussion has become unproductive |
| `spam` | Issue thread contains spam |

#### Develop

Create a development branch linked to the issue.

```bash
# Create branch and switch to it locally
gh issue develop $N --checkout

# Create branch with custom name
gh issue develop $N --name $BRANCH_NAME --checkout

# Create branch without checkout
gh issue develop $N
```

The branch name defaults to `{issue-number}-{issue-title-slug}`. The branch is automatically linked to the issue on GitHub.

#### Bulk Operations

Apply the same operation to multiple issues at once.

**Bulk label:**
```bash
# Pre-check: create any missing labels before applying
for LABEL in $(echo "$LABELS" | tr ',' '\n'); do
  if ! gh label list --search "$LABEL" --json name | jq -e ".[] | select(.name==\"$LABEL\")" >/dev/null 2>&1; then
    echo "Label '$LABEL' not found — skipping (create it first with: gh label create \"$LABEL\")"
    LABELS=$(echo "$LABELS" | sed "s/,$LABEL//;s/$LABEL,//;s/^$LABEL$//")
  fi
done
for N in $ISSUE_NUMBERS; do
  [ -n "$LABELS" ] && gh issue edit $N --add-label "$LABELS"
done
```

**Bulk assign:**
```bash
for N in $ISSUE_NUMBERS; do
  gh issue edit $N --add-assignee "$USERS"
done
```

**Bulk close:**
```bash
for N in $ISSUE_NUMBERS; do
  gh issue close $N
done
```

**Bulk reopen:**
```bash
for N in $ISSUE_NUMBERS; do
  gh issue reopen $N
done
```

Report success/failure count after bulk operations.

#### Custom Fields

Manage custom issue fields (requires org-level issue field configuration).

**List available fields:**
```bash
# Get org name from repo
ORG=$(gh repo view --json owner --jq '.owner.login')

# List fields
gh api orgs/$ORG/issue-fields --jq '.[] | "\(.id): \(.name) (\(.type))"'
```

**Get field values for an issue:**
```bash
gh api repos/$OWNER/$REPO/issues/$N/issue-field-values \
  --jq '.[] | "\(.field.name): \(.value)"'
```

**Set a field value:**
```bash
FIELD_ID=$(gh api orgs/$ORG/issue-fields --jq '.[] | select(.name == "$FIELD_NAME") | .id')

gh api repos/$OWNER/$REPO/issues/$N/issue-field-values \
  -X POST -f field_id=$FIELD_ID -f value="$VALUE"
```

If the repo is not in an organization, report: "Custom issue fields require an organization-level repository."

### Step 3: Report Results

| Operation | Report |
|-----------|--------|
| `transfer` | New issue URL in target repo |
| `pin/unpin` | Confirmation, current pinned issues list |
| `lock/unlock` | Confirmation with lock reason |
| `develop` | Branch name and URL, checkout status |
| `bulk` | Success/failure count per issue |
| `fields` | Field values table or confirmation of update |

## Error Handling

| Error | Cause | Action |
|-------|-------|--------|
| `unknown command "develop"` | Older `gh` CLI version | Report: "gh issue develop requires gh CLI 2.30+. Update with: gh upgrade" |
| 403 on transfer | No write access to target | Report permission requirement |
| 422 on pin | Already 3 pinned issues | List current pins, ask which to replace |
| 404 on issue-fields | Org doesn't have custom fields | Report: "Custom fields not configured for this organization" |

## Agentic Optimizations

| Context | Command |
|---------|---------|
| Transfer issue | `gh issue transfer N target-repo` |
| Pin issue | `gh issue pin N` |
| Lock issue | `gh issue lock N --reason resolved` |
| Create dev branch | `gh issue develop N --checkout` |
| Bulk close | Loop: `gh issue close N` for each N |
| List custom fields | `gh api orgs/{org}/issue-fields --jq '.[].name'` |
| Get field values | `gh api repos/{o}/{r}/issues/N/issue-field-values` |

## See Also

- **git:issue-hierarchy** skill for sub-issues and dependencies
- **github-issue-writing** skill for creating new issues
- **git:issue** skill for implementing/processing issues
- **gh-cli-agentic** skill for raw API command patterns
- [REFERENCE.md](REFERENCE.md) for custom fields API details