Issue create
Don't file first. Search and inspect before composing.
Dedup pre-flight
Open and closed — omitting --state searches both:
gh search issues "<keywords>" --repo <owner>/<repo> --limit 20
Read near-matches with gh api repos/:owner/:repo/issues/<N>. Decide:
- Same outcome already open — update the existing one
(
mcp__github__issue_write with method: update for the body,
mcp__github__add_issue_comment for new context). Don't file a new
one.
- Same outcome closed for stale reasons — reopen it
(
mcp__github__issue_write, method: update, state: open) with a
comment citing what changed. Don't file a new one.
- Adjacent (same area, different angle) — file new, cite the
existing in Additional context; consider an
issue-links edge.
- Partially covers — narrow the new issue to the uncovered
slice; cross-reference both ways.
- Nothing close — file new.
If torn, surface the call rather than silently pick.
Detect repo conventions
ls .github/ISSUE_TEMPLATE/ 2>/dev/null
# REST reads — see ~/.claude/CLAUDE.md "GitHub API budget".
gh api 'repos/:owner/:repo/labels?per_page=100' --jq '.[].name'
gh api repos/:owner/:repo/milestones \
--jq '.[] | "\(.number)\t\(.title)"' # open only — can't assign a closed one
gh api 'repos/:owner/:repo/issues?per_page=5&state=all' \
--jq '.[].title' # skim recent house style
Template present → read it and fill its fields into the body.
Templates encode the project's required fields; don't bypass with a
freeform body.
Standard structure (no template)
- Title — statement true when done. Active voice, outcome.
"Profile writes persist across API restarts in Firestore",
not "Fix profile persistence".
- Summary — 1-2 sentences. What this delivers.
- Motivation — what problem, dependency, or opportunity drives
it. Cite the trigger (PR review, incident, related issue).
- Scope — concrete changes, specific enough to start without
guessing. Bullets, not prose.
- Acceptance criteria — measurable conditions,
- [ ] task-list.
- Additional context — links, screenshots, related issues, only
when they help. Skip the section if empty.
Optimise for tokens — no filler, no restated headings, no "this
issue tracks the work to..." preambles.
Labels and milestones
- Pick existing labels. Don't invent inline — if nothing fits, skip
or raise the label question separately.
- Milestone: assign if one fits the outcome (convergence test —
closing the issue advances the milestone's description). Unset
otherwise. Never use milestones as labels.
- Creating a new milestone →
milestones skill.
- Relating to other issues/PRs →
issue-links skill, after submit.
Submit
Filing creates shared state — propose the body before submitting on
any non-obvious choice (scope, label call, dedup verdict).
File with mcp__github__issue_write (method: create):
labels — array of existing label names.milestone — the number from the listing above, not the title.
Procedure
- Search open + closed; decide update / reopen / new / link.
- Detect template; else prepare standard structure.
- Fetch labels and milestones; pick fitters or skip.
- Compose; surface non-obvious choices.
- Submit; capture URL.
- Apply cross-edges via
issue-links if related.
1---2name: issue-create3description: File a new GitHub issue in the checked-out repo — search first for duplicates/adjacent issues to update or reference, detect the repo's issue template if any, then compose title/body/labels/milestone matching house style. Use when asked to file, create, open, report, or track an issue.4---56# Issue create78Don't file first. Search and inspect before composing.910## Dedup pre-flight1112Open *and* closed — omitting `--state` searches both:1314```bash15gh search issues "<keywords>" --repo <owner>/<repo> --limit 2016```1718Read near-matches with `gh api repos/:owner/:repo/issues/<N>`. Decide:1920- **Same outcome already open** — update the existing one21 (`mcp__github__issue_write` with `method: update` for the body,22 `mcp__github__add_issue_comment` for new context). Don't file a new23 one.24- **Same outcome closed for stale reasons** — reopen it25 (`mcp__github__issue_write`, `method: update`, `state: open`) with a26 comment citing what changed. Don't file a new one.27- **Adjacent** (same area, different angle) — file new, cite the28 existing in *Additional context*; consider an `issue-links` edge.29- **Partially covers** — narrow the new issue to the uncovered30 slice; cross-reference both ways.31- **Nothing close** — file new.3233If torn, surface the call rather than silently pick.3435## Detect repo conventions3637```bash38ls .github/ISSUE_TEMPLATE/ 2>/dev/null3940# REST reads — see ~/.claude/CLAUDE.md "GitHub API budget".41gh api 'repos/:owner/:repo/labels?per_page=100' --jq '.[].name'42gh api repos/:owner/:repo/milestones \43 --jq '.[] | "\(.number)\t\(.title)"' # open only — can't assign a closed one44gh api 'repos/:owner/:repo/issues?per_page=5&state=all' \45 --jq '.[].title' # skim recent house style46```4748Template present → read it and fill its fields into the body.49Templates encode the project's required fields; don't bypass with a50freeform body.5152## Standard structure (no template)5354- **Title** — statement true when done. Active voice, outcome.55 *"Profile writes persist across API restarts in Firestore"*,56 not *"Fix profile persistence"*.57- **Summary** — 1-2 sentences. What this delivers.58- **Motivation** — what problem, dependency, or opportunity drives59 it. Cite the trigger (PR review, incident, related issue).60- **Scope** — concrete changes, specific enough to start without61 guessing. Bullets, not prose.62- **Acceptance criteria** — measurable conditions, `- [ ]` task-list.63- **Additional context** — links, screenshots, related issues, only64 when they help. Skip the section if empty.6566Optimise for tokens — no filler, no restated headings, no "this67issue tracks the work to..." preambles.6869## Labels and milestones7071- Pick existing labels. Don't invent inline — if nothing fits, skip72 or raise the label question separately.73- Milestone: assign if one fits the outcome (convergence test —74 closing the issue advances the milestone's description). Unset75 otherwise. Never use milestones as labels.76- Creating a new milestone → `milestones` skill.77- Relating to other issues/PRs → `issue-links` skill, after submit.7879## Submit8081Filing creates shared state — propose the body before submitting on82any non-obvious choice (scope, label call, dedup verdict).8384File with `mcp__github__issue_write` (`method: create`):8586- `labels` — array of existing label names.87- `milestone` — the *number* from the listing above, not the title.8889## Procedure90911. Search open + closed; decide update / reopen / new / link.922. Detect template; else prepare standard structure.933. Fetch labels and milestones; pick fitters or skip.944. Compose; surface non-obvious choices.955. Submit; capture URL.966. Apply cross-edges via `issue-links` if related.
alunduil