issue-triage

GitHub

自动化处理未归档Issue的两遍审查流程:第一遍自动打标、分类并计算优先级评分;第二遍由人工审批决定是否纳入版本。包含板卡审计与状态同步,确保Issue管理规范性。

.claude/skills/issue-triage/SKILL.md modelcontextprotocol/inspector

触发场景

triage new issues scoring an issue's Priority

安装

npx skills add modelcontextprotocol/inspector --skill issue-triage -g -y
更多选项

非标准路径

npx skills add https://github.com/modelcontextprotocol/inspector/tree/main/.claude/skills/issue-triage -g -y

不安装直接使用

npx skills use modelcontextprotocol/inspector@issue-triage

指定 Agent (Claude Code)

npx skills add modelcontextprotocol/inspector --skill issue-triage -a claude-code -g -y

安装 repo 全部 skill

npx skills add modelcontextprotocol/inspector --all -g -y

预览 repo 内 skill

npx skills add modelcontextprotocol/inspector --list

SKILL.md

Frontmatter
{
    "name": "issue-triage",
    "description": "Triage unboarded Inspector issues — the two-pass sweep, the priority rubric and its score comment, and the board audit that checks the whole board against its invariants. Use for \"triage new issues\" or when scoring an issue's Priority.",
    "disable-model-invocation": false
}

Triaging issues

An issue needs triage when it has no board card — regardless of who filed it. That is the whole test, and it is deliberately about state, not authorship. The milestone is not part of the test; it decides where the card lands (milestoned → Todo, unmilestoned → Incoming), so an approved-but-unboarded issue is still swept in rather than skipped (Copilot). An outside reporter has no board access, so their issue necessarily lands this way — but so does a maintainer's, whenever they open one by hand instead of through the /issue-create flow. Write access makes the board reachable, not automatic. What puts an issue in Todo is somebody performing the approval, and an issue nobody did that for has not been approved, whoever's name is on it.

"Triage new issues" means running pass 1 over every unboarded open issue, then the board audit. Pass 2 is a human judgment call and is never done unprompted.

Pass 1 — sweep them onto the board (no approval implied)

For each open issue with no card:

  1. Apply the version label (v2 unless it's a fix for released v1 behavior) and the type label (bug / enhancement / documentation / chore / question — see /issue-create for the table). An outside reporter cannot set either, so both are applied here.
  2. Add it to the board for that version — v2 → #28, v1 → #11.
  3. Set Status to Incoming.
  4. Set Priority with the rubric below (v2 only), and record the score in a comment. This is an assessment, not an approval — it's how the queue gets ordered for the maintainer who reviews it next.
  5. Leave the milestone unset. Nobody has committed to shipping it yet, and an empty milestone is precisely what marks it as awaiting review.

The one exception is an unboarded issue that already carries a milestone. Someone recorded the approval and only the card is missing, so board it straight into Todo, keeping the milestone. Otherwise triage would silently un-approve work a maintainer had already scheduled.

Finding the unboarded ones

Diff the open issues against both boards. Diffing against #28 alone is wrong: a v1 issue correctly carded on #11 is reported as unboarded and gets double-boarded (a real defect a past sweep introduced — #1929 reproduced it). The script (scripts/board-sweep.mjs, #2558) does the union, trusts each dump only when complete (a truncated listing makes a carded issue read as unboarded), and prints each unboarded issue with its destination — milestoned already → Todo, otherwise → Incoming:

npm run board:sweep     # exits non-zero when any unboarded issue exists

Pass 2 — approve what should ship

A maintainer reads the Incoming column and, for each issue worth doing, assigns a milestone and moves the card to Todo (or In Progress if picking it up now). That is the whole approval gesture.

This pass is a judgment call reserved for a human — deciding what ships in which release is not something to infer from a rubric. Never promote a card out of Incoming as part of a routine sweep; "triage new issues" stops at the end of pass 1.

Issues that shouldn't ship stay in Incoming (or get closed). Incoming is the review queue, and "milestoned" is the line between reviewed and not — which is why the milestone stays off in pass 1, and why the rubric can treat a milestone as a real signal rather than a formality every issue carries.

The priority rubric

Score it rather than assert it: rate two axes 1–5, add the signal bonuses, and read the total off the band table. The point is that two people triaging the same issue land in the same place, and that the reasoning survives in a form someone can argue with later.

Axis 1 — Severity / impact (1–5). How bad is it when it happens?

Score Means
1 Cosmetic — a typo, a misaligned control, a wording nit.
2 Minor friction with an easy workaround.
3 A real feature is broken or missing; the workaround is annoying or partial.
4 A core workflow is unusable, or the Inspector reports something false about the server under test.
5 Data loss, a security vulnerability, or a release that is broken on arrival for everyone.

Axis 2 — Urgency / staleness (1–5). How time-sensitive or neglected is it?

Score Means
1 No time pressure; nothing waits on it.
2 Wanted eventually.
3 Wanted this milestone, or has sat >90 days with no activity.
4 Blocking other work, or tied to a dated external dependency (an SDK release, a spec deadline).
5 Blocking a release, or actively hurting users on a published version right now.

Signal indicators (+1 each — not an axis of their own). Corroborating evidence that the two axes may have undercounted:

  • Carries a bug or security-related label
  • Linked to a milestone — i.e. already approved. This is the re-scoring case: an issue being scored in a pass-1 triage has no milestone yet by rule, so it never earns this one. If you find yourself applying it to every issue in a batch, the milestone is being used as a formality rather than as approval, and the bonus has become a constant that discriminates nothing.
  • High engagement (many comments or reactions)
  • Assigned to someone
  • A sub-issue of a larger epic
  • The reporter set Fields → Priority to Urgent or High — +1, flat, whichever of the two they picked. It does not map to a band, and Urgent earns exactly what High earns.

Bands. Axes give 2–10 and there are six bonuses, so the total runs 2–16.

Total Priority Meaning
12+ Urgent Drop what you're doing.
9–11 High Next up after current work.
6–8 Medium Scheduled normally.
≤5 Low Nice to have; may sit.

Severity alone doesn't reach Urgent: a 5/5 with no corroborating signals totals 10 and lands High. That's deliberate — Urgent is reserved for a severe problem that something else also confirms is burning, and a band that everything qualifies for stops carrying information. Override the band when it's plainly wrong, but say why in the issue; a rubric nobody may overrule is a rubric people route around.

Trust boundary: who can set what

The boards are private (public: false, both #28 and #11 — verified 2026-08-01). The Status and Priority a maintainer assigns are visible only to people with project access: a reporter cannot see them, cannot set them, and will never learn how their issue was scored. Board priority is a maintainers' working queue, not a published commitment.

The org-level Fields → Priority is the opposite. It renders on the public issue page and is not part of maintainer triage, so any value there is untrusted — we didn't put it there, and it carries a preference rather than an assessment. That asymmetry is why it earns a flat +1 and nothing more:

  • It counts for something. Someone flagging their own issue is real information about how much it hurts them.
  • It cannot decide an outcome. The bonus is capped, identical for Urgent and High, and can lift an issue at most one band. Nothing a reporter can type reaches Urgent by itself: Urgent needs 12, so the issue must already sit at 11 on maintainer-assessed axes — at which point the reporter is not the reason.
  • Never map the value across. A reporter selecting Urgent does not make the card Urgent. Doing that would hand queue position to anyone with a GitHub account, and the queue would sort by assertiveness instead of impact.

Don't lean on GitHub's permission gate to enforce this. Whether an outside reporter can set that field today is an implementation detail that can change without notice; the rule holds either way, because it rests on who assessed the issue rather than on who was technically able to click.

Recording the score

The board stores only the result — a card reading High with no trace of how it got there — and since the boards are private, that result is also invisible to the reporter. So post the arithmetic as a comment on the issue. Without it, a later re-scoring has no way to tell a considered judgment from a guess.

gh issue comment <N> --repo modelcontextprotocol/inspector --body \
'**Triage:** Priority **Medium** (total 7)

- Severity 3 — a real feature is broken; workaround is partial
- Urgency 2 — wanted eventually, nothing blocked on it
- Bonuses: +1 `bug` label, +1 reporter set Fields → Priority to High

Board: #28, Status `Incoming` (awaiting maintainer review — no milestone yet).'

Name the bonuses you claimed rather than just summing them — the milestone bonus in particular should be conspicuously absent on a pass-1 triage, and a comment that lists it is a visible sign the approval semantics were misapplied.

The board audit

Sweeping in the unboarded issues is only the most visible defect class. A board drifts in several other ways that no single-issue rule catches, so finish a triage run with the audit below — every check should print 0. A non-zero count means the board contradicts a rule, not that the rule needs revisiting.

Check Invariant Fix
Double-boarded An issue has a card on one board, the one matching its version label Delete the wrong-board card
Non-Issue items Only issues go on a board — never PRs, never drafts, except a [GHSA-…] draft on #28 Delete the item
No Status Every card carries a Status Set one — Incoming if unmilestoned, else by where it actually is
GHSA draft missing Status/Priority An exempted advisory draft still carries both Set them — /security-advisory
Incoming with a milestone (#28) Incoming ⇔ no milestone Approval was never recorded: move to Todo, or clear the milestone
Past Incoming without a milestone (#28) Everything past Incoming ⇔ milestoned Claims an approval nobody made: milestone it, or move back to Incoming
Wrong board for label v1 → #11, v2 → #28 Move the card to the right board
Not exactly one version label Every issue carries exactly one of v1/v2 Apply the missing one, or remove the extra
Not exactly one type label Every issue carries exactly one of the five types Classify it, or remove the extra
No Priority (#28) Every board item is prioritized Score it with the rubric
Closed, not shipped, still carded Done means the work shipped Delete the card
Open, but carded Done A card in Done ⇒ its issue is closed Close the issue, or move the card back
npm run board:audit     # one line per check; exits non-zero when any is dirty

The script (scripts/board-audit.mjs, #2558) prints <count>\t<check>\t<first offenders> for every invariant in the table above, over complete dumps only — a truncated listing would make every check lie, so it refuses one instead.

Two things its queries account for, both learned the hard way:

  • Filter by repository. These are org projects and can hold cards from any repo in the org — board #11 currently carries one modelcontextprotocol/servers issue. Without the .content.repository filter it reads as a statusless-card defect, and "fixing" it would mean editing another repo's tracking.
  • Done is checked from both sides. One direction catches a card parked in Done for work that never shipped; the other catches an issue still open under a Done card. The second is not hypothetical here — closing keywords do not fire on v2/main, so every v2 issue is closed by hand after its PR merges, and forgetting that step is the normal way this breaks (Copilot). The other checks cannot see it: they either gate on isopen or skip Done.
  • The two milestone checks are #28-only. Every milestone in this repo is a v2 release bucket, so a v1 issue has none it could take — running the Incoming⇔milestone invariant over board #11 would flag every card on it for a state it cannot reach. They also read Issue items only, which is what exempts a [GHSA- advisory draft on #28: it cannot carry a milestone, and its approval is the advisory's acceptance (/security-advisory step 3), which lives on the advisory rather than the board. The audit cannot see that, so a GHSA draft past Incoming is correct once its advisory is accepted and is not reported.
  • Count the labels; don't test for presence. The invariant is exactly one, so a predicate that only asks "is any version label present" passes an issue carrying both v1 and v2 — which belongs to two lines at once and shows up in both filtered queries. Same for the five type labels (Copilot).
  • Keep drafts inside own. A draft card carries no .content.repository, so a plain equality filter removes it before the "non-Issue" check can see it — and that check then reports 0 while the invariant it states (no drafts) is being violated (Copilot). The filter admits an item with no repository and excludes only cards that name a different one.
  • Advisory drafts are carved out of that check by TITLE, not by type. A GitHub security advisory is private until it is published, so it is tracked by a draft card titled [GHSA-xxxx-yyyy-zzzz] - … — the one exception AGENTS.md grants to "no draft cards", and the security-advisory skill is the flow. There are enough of them open at any time that counting them would pin this check permanently non-zero, and a check that never prints 0 stops being read at all. The discriminator is deliberately the title prefix and nothing broader: exempting all drafts, or every card whose Status is Incoming, would let an ordinary stray draft through, which is the defect the check exists for. So a draft titled anything else is still reported — by title, since a draft has no issue number to print. ⚠️ The title prefix alone is not enough, because a title is not a type and not a board. Matched on its own it would also exempt a pull request whose title happens to start [GHSA- — a plausible title for a security fix — and an advisory draft misfiled on #11, where the replacement field check below does not look either, so both checks would read 0. The exemption is therefore DraftIssue and [GHSA- and board #28; #11 still reports every non-Issue item it carries. ⚠️ The exemption had to come with a replacement check. $B28 and $B11 are built from Issue items only, so the no Status and no Priority checks never see a draft — before the carve-out the non-Issue check was the only thing looking at one, and exempting drafts there alone would have made a half-made advisory card invisible to the entire audit. Hence GHSA draft missing Status/Priority, which reads the item-level .status and .priority that item-list exposes for a draft as it does for an issue.
  • $M holds closed issues too — the lookup is built from gh issue list --state all, which it has to be, because the last check reads closed issues' state reasons. So isopen is not there to cope with a missing entry; it is there because the invariants are about open work. A closed issue legitimately sits in Done with whatever milestone it had, and a check that did not gate on isopen would report every one of them (Copilot).

Do not "fix" a Done card that is missing a milestone. Cards predating a rule are not defects to backfill in bulk — the audit exists to stop new drift, and rewriting settled history destroys the record of when a rule started being enforced.

版本历史

  • 074b810 当前 2026-10-20 02:50

    将skill中的模板代码块转换为可测试的脚本(如board:sweep),提升可靠性与可维护性。

  • 1e31c78 2026-09-28 17:12

    修复项目列表查询截断导致的误判问题:增加对item-list完整性的检查,失败时中止操作;优化ID清理逻辑防止残留;调整查询限制以确保数据准确性。

  • 2e90a62 2026-09-23 06:47

同 Skill 集合

.claude/skills/board-ops/SKILL.md
.claude/skills/issue-create/SKILL.md
.claude/skills/local-dev/SKILL.md
.claude/skills/pr-flow/SKILL.md
.claude/skills/pre-push-gate/SKILL.md
.claude/skills/project-structure/SKILL.md
.claude/skills/release/SKILL.md
.claude/skills/security-advisory/SKILL.md
.claude/skills/test-servers/SKILL.md
skills/mcpdo/SKILL.md
.claude/skills/testing/SKILL.md

元信息

文件数
0
版本
074b810
Hash
7539f10b
收录时间
2026-09-23 06:47

首页 - Wiki
Copyright © 2011-2026 iteam. Current version is 2.156.0. UTC+08:00, 2026-11-21 16:28
浙ICP备14020137号-1