Github Issues

github-issues

Purpose

Standardize GitHub issue creation and management across any project. Ensure every issue has a clear structure, proper labels, and actionable content. Guide the user through creating well-formed issues and applying GitHub's default label taxonomy consistently.

Prerequisites

Before any operation, verify the environment:

1. Detect repository context:

git remote get-url origin

Parse owner and repo from the remote URL. Supports both formats:

• SSH: git@github.com:owner/repo.git
• HTTPS: https://github.com/owner/repo.git

Store the result as REPO="owner/repo". If not in a git repository or no remote is configured, ask the user to specify owner/repo manually and store it as REPO.

Perform this parsing step before running any gh issue or gh label commands. When constructing gh issue or gh label commands, include -R "$REPO" so they always target the correct repository, regardless of whether the user is inside a local clone.

When to use

• Creating a new GitHub issue (with a duplicate check first — updating an existing issue when one already covers the request)
• Viewing issue details
• Closing issues with explanation
• Commenting on existing issues
• Triaging or labeling existing issues
• Listing open issues with their labels

Detailed references

Load these on demand — don't read them up front:

• references/issue-templates.md — title rules, the enhancement and bug body templates, the body-section rules, and type detection from title/context. Read before writing or rewriting an issue body.
• references/labels.md — the type/status label taxonomy, how to validate a label exists before applying it, and the --add-label vs --label rule. Read before applying or changing labels.

Operations

Based on $ARGUMENTS, perform ONE of these operations:

create <title>

1. Determine the issue type from the title and context — see the type-detection indicators in references/issue-templates.md.
2. Check for an existing issue covering the same thing — before creating anything. Filing a second issue for a problem that already has one fragments the discussion and wastes triage effort, so always search first. Pull the most distinctive keywords from the title (drop generic verbs like "add"/"fix" and stop-words) and search across both open and closed issues:

gh issue list -R "$REPO" --search "<keywords>" --state all --json number,title,state,url,updatedAt --limit 20

Read the candidates and judge whether any describes the same underlying request or bug — not just a keyword overlap. Two issues that touch the same file but ask for different things are not duplicates; two issues worded differently that would be resolved by the same change are. When unsure, treat the closest candidate as a possible match and let the user decide rather than guessing.

• No real match: proceed to step 3 and create a new issue.
• A matching OPEN issue exists: do not create a duplicate. Open it (gh issue view <number> -R "$REPO") and compare its body against the new details. If the request brings genuinely new information (extra repro steps, an affected file the issue is missing, a clearer proposed solution, new context), update the existing issue instead — see step 6b. If the existing issue already covers everything, tell the user it's already filed (with the link) and stop without changing anything.
• A matching CLOSED issue exists: surface it to the user with its link and state. Ask whether to reopen it (if the problem has resurfaced), add the new context as a comment, or file a fresh issue (e.g. the old one was a different root cause). Don't reopen silently.

3. Check which labels are available in the target repository and handle any missing type label — follow references/labels.md.
4. Select the matching body template (enhancement or bug) from references/issue-templates.md and pre-fill the "Summary" section from context. If the user has provided enough detail, fill all applicable sections. Otherwise, ask for the missing required sections — especially "Proposed Solution" with specific file paths and implementation approach.
5. Suggest appropriate labels based on the type detection and available labels discovered in step 3.
6. Present the full issue (title, body, labels) for user review before creating. Wait for confirmation or edits.
7. Create the issue:

gh issue create -R "$REPO" --title "<title>" --label "<label1>,<label2>" --body "$(cat <<'EOF'
<body content>
EOF
)"

8. Output the issue URL.

Step 6b: Updating an existing issue instead of creating

Reached only when step 2 found a matching open issue that's missing information the new request provides. The goal is to enrich the existing issue without clobbering what's already there — its body may contain edits, discussion references, or detail the user added by hand.

1. Decide what genuinely needs to change. For a small addition (an extra repro step, a link, a newly identified cause), a comment is the least destructive and keeps an audit trail:

gh issue comment <number> -R "$REPO" --body "$(cat <<'EOF'
<the new information, e.g. additional repro steps or an affected file>
EOF
)"

2. If the issue's structured body is materially incomplete (missing the "Proposed Solution", wrong/empty "Summary") and rewriting it makes the issue clearer, edit the body — but show the user the proposed new body first and merge with the existing content rather than replacing it wholesale:

gh issue edit <number> -R "$REPO" --body "$(cat <<'EOF'
<merged body — existing content plus the new details>
EOF
)"

3. If the new context changes the categorization (e.g. it turns out to be a bug, not just an enhancement), add the appropriate label with --add-label (never --label, which would wipe existing labels).
4. Output the issue URL and a one-line note of what you changed.

view <number>

1. Display the issue details:

gh issue view <number> -R "$REPO"

2. If the user wants to see discussion, show comments:

gh issue view <number> -R "$REPO" --comments

close <number> [reason]

1. Fetch the issue to verify state:

gh issue view <number> -R "$REPO" --json title,labels,state

2. If the issue is already closed, inform the user and stop.
3. If closing as duplicate, require the user to specify the original issue number. Verify the original issue exists, then validate the duplicate label and close:

gh issue view <original> -R "$REPO" --json number,title,state
gh label list -R "$REPO" --json name --jq '.[].name' | grep -q '^duplicate$'
gh issue comment <number> -R "$REPO" --body "Closing as duplicate of #<original>."
gh issue close <number> -R "$REPO" --reason "not planned"
gh issue edit <number> -R "$REPO" --add-label "duplicate"

If the duplicate label does not exist, ask the user whether to create it or skip labeling — the comment and close are sufficient on their own.

Note: gh issue close --reason only accepts completed or not planned. For duplicates, use not planned — the duplicate label and comment provide the actual context.

4. For other closures, add a comment explaining why, then close:

gh issue comment <number> -R "$REPO" --body "<reason>"
gh issue close <number> -R "$REPO"

5. If the user provides a reason in the arguments, use it. Otherwise, ask for a reason before closing — never close silently.

comment <number> <text>

1. Verify the issue exists:

gh issue view <number> -R "$REPO" --json number,title,state

2. Add the comment:

gh issue comment <number> -R "$REPO" --body "<text>"

3. Confirm the comment was posted with a link.

assign <number> <user> [--remove]

1. Verify the issue exists:

gh issue view <number> -R "$REPO" --json number,title,state,assignees

2. If --remove is not provided, assign the user:

gh issue edit <number> -R "$REPO" --add-assignee "<user>"

If --remove is provided, unassign:

gh issue edit <number> -R "$REPO" --remove-assignee "<user>"

3. If <user> is @me or me, resolve to the authenticated user:

gh api user --jq '.login'

4. Confirm the assignment change.

label <number> <label> [--remove]

1. Fetch available labels to validate the requested label exists:

gh label list -R "$REPO" --json name --jq '.[].name'

2. Add or remove the label with --add-label / --remove-label — see references/labels.md for the exact commands and why --label must never be used on gh issue edit.
3. If the label does not exist, warn the user and list available labels. Suggest the closest match if possible.

triage

1. List all open issues with their labels:

gh issue list -R "$REPO" --state open --json number,title,body,labels,createdAt --limit 100

2. Filter for issues where labels is empty.
3. If no unlabeled issues are found, inform the user ("All open issues are labeled") and stop.
4. Analyze the title and body of each unlabeled issue to suggest a label, using the type-detection indicators in references/issue-templates.md and the taxonomy in references/labels.md.
5. Present a summary table with suggested labels:

#   Title                                    Suggested Label
37  Add database corruption recovery         enhancement
33  Fix error state on successful ops        bug
30  Update API documentation                 documentation

6. Ask the user to confirm, modify, or skip each suggestion before applying.
7. Apply confirmed labels:

gh issue edit <number> -R "$REPO" --add-label "<label>"

list (default when no arguments given)

1. List open issues:

gh issue list -R "$REPO" --state open --json number,title,labels,assignees --limit 50

If --label <label> is specified in the arguments, add --label "<label>" to filter.

2. Display in a readable table format:

#   Title                                    Labels              Assignee
12  Add dark mode toggle                     enhancement         @user
11  App crashes on startup with empty DB     bug, good first     —
10  Update README with build instructions    documentation       @user

3. Show summary: total count and label distribution.
4. If there are more issues than the displayed limit, inform the user and suggest using --label to filter or increasing the limit.

Error handling

Constraints

These rules keep issue quality high and prevent accidental damage to existing labels and issues:

• Search for an existing issue before creating a new one, and update that issue rather than filing a duplicate — duplicate issues split discussion and double the triage burden
• Every issue needs at least one type label — labels are the primary categorization mechanism and enable filtering and triage
• Present the full issue (title, body, labels) for user review before creating — the user owns the final content
• Add a comment explaining why before closing any issue — future readers need to understand the decision
• Link the original issue before closing as duplicate — this preserves the relationship in GitHub's UI
• Use --add-label (not --label) when editing issues — --label replaces all existing labels, which can silently remove important categorization
• Do not create new labels without user confirmation — labels are shared across the entire repository and affect everyone's workflow
• Include specific file paths and code references in issue bodies when context is available — actionable issues with concrete pointers get resolved faster