issue-conventions-guide

Issue Conventions — Dispatcher

This skill routes work to a subagent. It carries no taxonomy rules of its own — rules and issue bodies stay in the subagent so they never enter the session context.

Step 1: Resolve the config

Read the first that exists: .claude-plugin/issue-conventions.json → .claude/issue-conventions.json → ~/.claude/issue-conventions.json.

A hit without a taxonomyDocument field counts as no taxonomy.

No config, or the document is missing or unparseable: do NOT invent a taxonomy and do NOT block the operation. Apply whatever labels already exist in the repo, say once per session — "This repo has no issue taxonomy; /issue-conventions-setup can design one" (or name the broken path) — then carry on.

Step 2: Route

Pick the row that matches what is about to happen. Launch the subagent with the instruction file as its system prompt, and pass it the taxonomyDocument path plus the issue data. Use models.<key> and efforts.<key> from the config.

Situation	Instructions	Model key
A new issue is being created	${SKILL_DIR}/references/classify-new.md	classifyNew
An existing issue changes scope, priority, severity, or classification; or is closed with a reason	${SKILL_DIR}/references/reclassify.md	reclassify
Several issues at once (splitting an epic, a small cleanup)	${CLAUDE_PLUGIN_ROOT}/templates/batch-classify.md	batchClassify
The whole backlog	stop — tell the user to run /issue-conventions-relabel	—
"Is everything still consistent?"	stop — tell the user to run /issue-conventions-drift	—

The subagent cannot see this conversation. Pass it a 2–3 sentence summary of what the issue is about, alongside the issue number or the draft title and body.

Step 3: Act on what comes back

Every classification subagent returns the same shape:

{ "labels": ["type:x", "priority:y"], "title": "...", "confidence": "high|low",
  "question": null }

• question is null — apply it. Labels go in one call: gh issue create --label "a,b,c". For an edit use --add-label / --remove-label, never --label (it overwrites).
• question is set — it holds text and options. Raise it with AskUserQuestion in this session (the subagent has no such tool), then apply the answer. If the answer reads like a general rule rather than a one-off, offer to add it to the document's disambiguation section.