| name | Filing GitHub Issues |
| description | File well-crafted GitHub issues. Use when the user wants to report a bug, request a feature, propose a change, or file any GitHub issue. Searches for duplicates, asks clarifying questions, and creates the issue using the gh CLI.
|
Filing GitHub Issues
A good issue gives a reader everything they need to understand the problem
without prescribing a solution. It states what is wrong or what is missing,
why it matters, and how to observe it. The reader should finish with a clear
picture of the problem and enough context to investigate independently.
Process
Follow these steps in order. Do not skip steps.
1. Identify the target repository
Determine which repository should receive this issue:
- If the user specifies a repo, use it.
- If the current working directory is a git repo, default to its
origin remote.
- If neither applies, ask.
Run gh repo view to confirm you have access and note the repo's full owner/name.
2. Search for existing issues
Before writing anything, search for duplicates and related issues:
gh issue list --repo <owner/name> --state all --search "<key terms>"
Try at least two different search queries using different terms from the user's
description. Search broadly — use core nouns and verbs, not the user's exact
phrasing.
If you find related issues:
- Present them to the user with issue number, title, and a one-line summary.
- Ask whether any of these captures their intent, whether the new issue should
reference them, or whether to proceed with a new issue.
- Do not file a duplicate without the user's explicit go-ahead.
3. Ask clarifying questions
Think divergently about what this issue needs before you write it. Consider
the problem from multiple angles:
- Who is affected? End users, developers, CI systems, downstream consumers?
- What triggers it? Specific actions, configurations, timing, data shapes?
- Where does it manifest? Which component, service, environment, platform?
- When did it start? Always been this way, or a regression? What changed?
- What is the severity? Workaround available? Blocks other work?
- What is the scope? Isolated incident or pattern? How many people hit this?
- What has been tried? Prior debugging, workarounds, related PRs?
- What context would a stranger need? Version numbers, error messages, logs,
screenshots, links to related discussions?
From these angles, identify the gaps — what the user hasn't told you but a
reader would need. Then ask your clarifying questions:
- Ask only questions whose answers would materially change the issue. Skip
anything you can fill in yourself from context.
- Prefer multiple-choice or yes/no questions over open-ended ones.
- Ask all your questions in a single message, grouped logically.
- Three to five questions is typical. Fewer is fine. More than seven means
you should narrow your focus.
Wait for the user's answers before proceeding.
4. Write the issue
Draft the issue title and body.
Title: A concise phrase that a reader can scan in a list and understand
without opening the issue. Lead with the component or area if the repo uses
that convention. Avoid vague words like "issue with" or "problem in."
Body structure — use only the sections that apply:
- What happens: The current behavior, stated as fact. Include error messages,
symptoms, or the observable gap.
- What should happen: The expected or desired behavior. Be specific enough
that someone could verify a fix against this description.
- How to reproduce: Numbered steps, starting from a clean state. Include
the environment, version, and configuration that matter. Omit this section
for feature requests or design issues.
- Context: Why this matters. Who it affects. What prompted this report.
Links to related issues, discussions, or documentation.
What to leave out:
- Do not propose a solution in the issue body. The issue captures the problem;
solutions belong in follow-up discussion or linked PRs.
- Do not pad the issue with generic text, boilerplate, or pleasantries.
- Do not add sections with no content. If you have nothing for "How to
reproduce," omit the section entirely.
Present the draft to the user. Wait for approval or edits before filing.
5. File the issue
After the user approves the draft:
gh issue create --repo <owner/name> \
--title "<title>" \
--body "$(cat <<'EOF'
<body>
EOF
)"
Return the issue URL to the user.
Sub-issues (parent / child in GitHub)
When the user wants a child issue under a parent (epic, breakdown, hierarchy),
GitHub’s sub-issue relationship is not created by the issue body. Text like
“Part of #N” or cross-links is optional for readers only; the graph stays flat
without an API call.
After creating the parent and child (parent first, then child), link them with
the REST sub-issues API:
- Resolve the child’s database
id (integer), which is not the issue
number, and assign it (example: CHILD_ID=$(gh api ... --jq .id)):
CHILD_ID=$(gh api repos/<owner>/<name>/issues/<child_number> --jq .id)
- Attach the child to the parent:
echo "{\"sub_issue_id\": $CHILD_ID}" | gh api repos/<owner>/<name>/issues/<parent_number>/sub_issues \
--method POST --input -
Use "replace_parent": true in the JSON body only when moving a child that
already has a parent.
- Confirm:
gh api repos/<owner>/<name>/issues/<child_number>/parent
GraphQL (alternative): addSubIssue with parent and child node IDs, or
createIssue with parentIssueId when the child is created in the same step.
Do this after each gh issue create succeeds; then return all issue URLs.
Constraints
- Never file without user approval. Always present the draft and wait.
- Never propose solutions. The issue describes the problem. Period.
- Never invent facts. If you lack information, ask. Do not guess at version
numbers, error messages, or reproduction steps.
- Respect the repo's conventions. If existing issues use a template or
follow a pattern, match it. Check
.github/ISSUE_TEMPLATE/ if it exists.
- Sub-issues: If there is a parent/child hierarchy, use GitHub’s sub-issue
API after creation; do not rely on body mentions alone.
