refactor(claude-ops): rename troubleshoot skill to known-issues

[kyle-sexton]

What

Atomic rename of the claude-ops:troubleshoot skill to claude-ops:known-issues, per the shadowed-skill-renames contract (#256):

• git mv plugins/claude-ops/skills/troubleshoot → skills/known-issues (directory and frontmatter name move together).
• Description sharpened to third-person what+when; "troubleshoot" and "is this broken" are kept as trigger words.
• Repo-wide reference sweep: sibling skills (changelog, observability incl. read-routing and evals, setup incl. evals), ${CLAUDE_PLUGIN_ROOT}/skills/... script paths, plugin.json description + registry_dir option description, plugin README, root README. "Troubleshooting registry" prose is now "known-issues registry".
• plugins/claude-ops version bump 0.9.0 → 0.10.0 (0.x breaking-by-minor precedent) with a CHANGELOG breaking-rename entry.

Why

The skill looks up and tracks KNOWN upstream Claude Code / Anthropic product issues (GitHub bug search, service health, persistent tracked-issue registry). It never diagnoses or fixes anything locally — "troubleshoot" over-promised a diagnostic capability the skill does not have.

Breaking

/claude-ops:troubleshoot no longer exists; invoke /claude-ops:known-issues. No renames-map entry (clean break per contract). Registry location, registry_dir semantics, actions, and behavior are unchanged.

Verification

• git grep sweep: zero remaining claude-ops:troubleshoot, /troubleshoot, or skills/troubleshoot references outside historical CHANGELOG entries. Remaining "troubleshooting" occurrences are deliberate: generic keyword/tags in plugin.json/marketplace.json, the SKILL description trigger word, the external docs.claude.com/.../troubleshooting URL, historical CHANGELOG 0.6.0 and docs/topics/plugin-organization/PLAN.md records, and unrelated plugins (songwriting suno, debugging tags).
• All touched JSON validated with jq; frontmatter name matches the directory (fresh-fetched https://code.claude.com/docs/en/skills).
• markdownlint-cli2 over plugins/claude-ops/**/*.md + README.md: 0 errors.
• New claude-ops:plugins skill untouched beyond none-needed; no vendor/ or .work/ edits.

🤖 Generated with Claude Code

https://claude.ai/code/session_01YVApnNGoKxYMJKNQx1QK8C

Related

• Program contract: program: shadowed-skill-renames contract (naming grammar rollout) #280 (shadowed-skill-renames naming grammar rollout)
• Conventions PR: docs: codify skill-naming grammar and cross-plugin reference rules #256

No linked issue — program-level rename executed under #280.

[claude]

Claude finished @kyle-sexton's task in 2m 12s —— View job

---

PR Review: refactor(claude-ops): rename troubleshoot skill to known-issues

Tasks

• Gather context and understand the PR scope
• Diff the PR changes
• Verify rename completeness (no stale troubleshoot refs)
• Check frontmatter, plugin.json, CHANGELOG, and version bump
• Review evals and script paths for correctness
• Post final review

---

Verdict: Approve ✓

This is a well-executed atomic rename. The sweep is complete, the intent is sound, and all the moving parts are consistent. Details below.

---

Rename completeness

git grep over plugins/claude-ops/ for skills/troubleshoot, :troubleshoot, troubleshoot skill, and /troubleshoot" returns zero hits outside of CHANGELOG historical entries. The skills/troubleshoot/ directory no longer exists; skills/known-issues/ is in its place.

The following cross-references were correctly updated:

Location	What changed
known-issues/SKILL.md	frontmatter name: known-issues; description keeps "troubleshoot" and "is this broken" as trigger words ✓
plugin.json	version 0.10.0; description and registry_dir option prose
changelog/SKILL.md	/known-issues in "Distinct from" list
observability/SKILL.md, read-routing.md	section heading + inline refs both updated
observability/evals.json	eval name + expected_output + expectation strings
setup/SKILL.md, setup/evals.json	description trigger words + eval prompt
scripts/check-all.sh	help-text backend reference
scripts/registry_manager.py	module docstring
Root README.md, plugins/claude-ops/README.md	prose updated

Version bump

0.9.0 → 0.10.0 is correct — this repo treats 0.x minor bumps as breaking by convention (per the PR body's "0.x breaking-by-minor precedent"), and this is a breaking rename.

CHANGELOG

The ## [0.10.0] entry clearly describes the breaking rename, the migration path (/claude-ops:troubleshoot → /claude-ops:known-issues), and the fact that behavior, actions, and registry_dir semantics are unchanged. No date is present, but that is consistent with all other version headers in this file (## [0.9.0], ## [0.8.0], etc.) — the existing project convention.

Intentional "troubleshooting" survivors

The PR body correctly identifies these remaining occurrences as intentional:

• marketplace.json and plugin.json keyword "troubleshooting" tag — search-discoverability, not a skill name
• SKILL.md description trigger words "troubleshoot" / "is this broken" — required for routing
• Historical CHANGELOG 0.6.0 entry and docs/topics/plugin-organization/PLAN.md
• Unrelated plugins (songwriting, debugging) that use "troubleshooting" in their own contexts

No renames-map entry

Confirmed absent — this is a clean break per the shadowed-skill-renames contract (#256). Consumers must update their invocations. The CHANGELOG entry communicates this adequately.

No issues found

No correctness bugs, security concerns, or policy violations. The rename is complete, consistent, and the rationale (the old name over-promised a local-diagnostic capability the skill never had) is solid.