inspector/.claude/skills/issue-create/SKILL.md
cliffhall d05e76d470 chore: address Copilot review round 4
- verify:skills:cli — the authoritative validator is now a GUARANTEED step in
  `local:gate` and CI, not a best-effort hand-off. It resolves the CLI itself
  (an installed one at 2.1.233+, else a pinned `npx -y`), so both tiers run the
  same script and cannot drift. `verify:skills` keeps skipping when the CLI is
  absent, which is right for `validate`: fast, offline, no Claude Code required.
- skill-manifest: the 1,536-char listing-entry cap covers `description` +
  `when_to_use` together; checking the description alone passed an over-cap
  entry. `when_to_use` is now parsed, validated and counted, with boundary tests
  at 1,536/1,537.
- verify-skills: report the budget as *this repo's contribution*. The real
  listing budget is shared with bundled skills and the contributor's own
  ~/.claude/skills, none of which is visible from here, so the number was
  claiming more than it measured.
- skill-eval: a negative case now means "no skill OF THIS REPO'S fired". It
  failed on any Skill invocation, so a contributor with an unrelated global
  skill got a false failure about their environment rather than these skills.
- docs/architecture + local-dev: the Node backend runner gets its
  `@inspector/core` alias from `clients/web/tsup.runner.config.ts`, not from
  Vite. The old text sent runner work to the wrong config.
- local-dev: the tarball does not ship "only each client's build/" — the
  allowlist also carries `clients/web/dist`, `clients/web/static` and the
  install helper. States the invariant that actually matters instead.
- issue-triage: the test for needing triage is "no board card". Adding "and no
  milestone" would skip the approved-but-unboarded case the same section then
  handles. Also corrected the `$M` note: the lookup is `--state all`, so closed
  issues DO have entries — `isopen` is about the invariants, not the lookup.
- issue-create: replaced "all five" with a per-version table. Steps 3 and 6
  (milestone, Priority) do not exist for v1, so the old list opened with a rule
  the same skill later tells you to violate.

Signed-off-by: cliffhall <cliff@futurescale.com>
2026-08-29 01:47:43 -04:00

6.1 KiB

name description disable-model-invocation
issue-create Create a tracked Inspector issue end to end — version label, type label, milestone, board card, Status and Priority. Use when filing a new issue, or when work discovered mid-task needs an issue of its own. true

Creating an issue

An issue you create is not "created" until every step below that applies to its version is done. A label is a repo tag, the milestone is a release bucket, and the board is a separate org project — --label v2 does not add a board card, and adding a card does not set a Status or a Priority.

# Step v2 v1
1 Version label — exactly one of v1 / v2 ✅ ✅
2 Type label — exactly one of bug / enhancement / documentation / chore / question ✅ ✅
3 Milestone ✅ ❌ — every milestone is a v2 release bucket, so there is none to take
4 A card on the board for that version — v2 → #28, v1 → #11 ✅ ✅
5 Status on that card ✅ ✅
6 Priority on that card ✅ ❌ — board #11 has no such field

The two ❌ rows are not oversights to fix later: the field does not exist for that line, and AGENTS.md states both exceptions (Copilot).

Set the labels and milestone at create time, never by backfilling: an unlabeled issue belongs to no version line and appears in no version-filtered query, and an unmilestoned one drops out of release planning silently.

Never create a duplicate. Check the board for a matching item first. Never create a draft card (a board card with no issue number) — every board item is a real GitHub issue.

0. Check the board first

gh issue list --repo modelcontextprotocol/inspector --state open --limit 1000 \
  --search "<keywords>" --json number,title,labels,milestone

1. Pick the labels

Version. v2 is the default for anything new. v1 is reserved for the narrow case of patching the deprecated line (security fixes only). If the target version isn't obvious, it's v2 — only ask when the issue is specifically a fix for released v1 behavior and it's unclear whether v2 still has the bug.

Type. Independent of the version label; every issue needs both.

Type Use for Not for
bug Something is broken, wrong, or regressed against its intended behavior A missing capability that was never built
enhancement A new capability, or extending an existing one — features, spec support, tracking issues A cleanup with no behavior change
documentation Prose deliverables — READMEs, guides, specification/ docs, AGENTS.md rules Code that happens to need a doc update
chore Maintenance with no user-facing behavior change — deps, build/CI tooling, refactors Anything a user would notice
question An open question or discussion with no agreed deliverable yet Work someone has already decided to do

Don't force the binary. bug and enhancement are the two most reached for, and pressing a docs task or a dependency pin into enhancement degrades it to "not a bug", at which point filtering by it stops telling you anything.

2. Pick the milestone

If the user didn't specify one, default to the current milestone: the open one with the nearest due date.

gh api repos/modelcontextprotocol/inspector/milestones --jq \
  'map(select(.state=="open")) | sort_by(.due_on) | .[] | "\(.title)\tdue \(.due_on[0:10])\topen=\(.open_issues)"'

Milestones are release buckets (v2.1.0, v2.2.0, …), so pick by when the work ships, not by size. If a new issue plainly can't make the current milestone, say so and put it in the next one rather than leaving it blank. Sub-issues normally inherit their parent's milestone.

⚠️ Every milestone is a v2 release bucket. There is no v1 bucket, so a v1 issue cannot satisfy the milestone rule — don't drop it in a v2.x one. Leave it unmilestoned and say so.

3. Create it

gh issue create --repo modelcontextprotocol/inspector \
  --title "<title>" \
  --label v2 --label bug \
  --milestone "v2.5.0" \
  --body "<body>"

4. Board it, in Todo

Filing an issue for work you intend to happen is approving it, so it starts in Todo with its milestone already set — not in Incoming, which is the queue for issues nobody has evaluated yet. Work you are starting immediately goes straight to In Progress.

Run the add-card recipe in /board-ops with Status → Todo and the Priority you scored. The project, field and option IDs live there and only there: an option ID is regenerated whenever its field's option list is edited, so a second copy here would go stale silently and break issue creation even after board-ops was fixed.

For a v1 issue, the same recipe against board #11 — no Priority, that board has no such field.

The priority rubric is in /issue-triage.

Note on issues that arrive from elsewhere

An issue opened through the GitHub UI — by an outside reporter or by a maintainer — arrives with no milestone and no card, and that is normal on arrival rather than a defect to fix the moment it lands: it comes into the system through /issue-triage instead, and starts in Incoming, because nobody has approved it.

Its labels are partly set already, which the triage pass has to account for: blank issues are disabled, so it came through a form in .github/ISSUE_TEMPLATE/ (Copilot).

Form Applies Still missing
Bug report bug the version label — the form carries a version-line dropdown a maintainer reads at triage, because a labels: list is static and GitHub cannot map an answer to a label
Feature request enhancement, v2 nothing — v1 takes security fixes only and cannot receive a feature, so v2 is correct by construction

So a bug report needs its version label applied from the dropdown answer, and a feature request usually needs no label work at all. ⚠️ GitHub serves the chooser from the default branch, so a form edited on v2/main does not take effect until the next milestone merge.