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

README.md

@@ -81,7 +81,7 @@ Browse and manage with `/plugin`. To refresh after updates: `/plugin marketplace
 - [`playbooks`](plugins/playbooks) — Doctrine and knowledge playbooks as on-demand skills, plus a maintainer-facing update skill. boris — Boris Cherny's Claude Code workflow tips (howborisusesclaudecode.com); thariq — Anthropic's internal skill-authoring playbook; fable-5 — Claude Fable 5's operating doctrine (self-authored, no upstream). The boris and thariq packs vendor a verbatim upstream baseline; /playbooks:update drift-checks and syncs those baselines centrally (maintainers).
 - [`claude-config`](plugins/claude-config) — Three audit skills for a repo's Claude Code configuration: audit (settings.json / .mcp.json / hooks / plugins / permissions drift), automation-gaps (evidence-gated verdicts on automation gaps), and permission-hygiene (allow-rule / allowed-tools grants for auto-mode durability and portability).
 - [`claude-memory`](plugins/claude-memory) — Audits the Claude Code instruction/memory layer — CLAUDE.md, CLAUDE.local.md, .claude/rules/, and auto-memory — against a checklist derived from official Claude Code documentation. A deterministic script-backed spine (MEMORY.md index integrity, orphan always-loaded rules) yields identical findings on identical repo state; judgment-tier checks apply fixed criteria with model reading. Actions: audit (default), fix (per-item approval), update (refresh criteria from current docs), report.
-- [`claude-ops`](plugins/claude-ops) — Claude Code operations toolkit. Five skills: observability (read locally captured telemetry — OTEL store, collector, hook-event JSONL, ccusage — with trend reports and store pruning), troubleshoot (search known Claude product GitHub bugs, check service health, maintain a persistent tracked-issue registry), changelog (ingest Claude Code changelog entries and integrate them into the current repo), plugins (bring a machine's plugin fleet current on demand — marketplace refresh, effective-scope updates including in-repo project/local installs, new-plugin install per policy, scope-divergence detection and explicit convergence), and a re-runnable setup action that settles where the troubleshooting registry lives. Plus a family of seven advisory *-audit telemetry-emitter hooks (API errors, config changes, instruction loads, permission denials, pre-compaction, skill usage, tool failures) that emit the shared hook-telemetry envelope, and a reference sink that maps envelopes into the hook-events.jsonl the observability skill reads.
+- [`claude-ops`](plugins/claude-ops) — Claude Code operations toolkit. Five skills: observability (read locally captured telemetry — OTEL store, collector, hook-event JSONL, ccusage — with trend reports and store pruning), known-issues (search known Claude product GitHub bugs, check service health, maintain a persistent tracked-issue registry), changelog (ingest Claude Code changelog entries and integrate them into the current repo), plugins (bring a machine's plugin fleet current on demand — marketplace refresh, effective-scope updates including in-repo project/local installs, new-plugin install per policy, scope-divergence detection and explicit convergence), and a re-runnable setup action that settles where the known-issues registry lives. Plus a family of seven advisory *-audit telemetry-emitter hooks (API errors, config changes, instruction loads, permission denials, pre-compaction, skill usage, tool failures) that emit the shared hook-telemetry envelope, and a reference sink that maps envelopes into the hook-events.jsonl the observability skill reads.
 - [`skill-quality`](plugins/skill-quality) — Skill-authoring QA tooling: a static contract checker that runs seventeen deterministic checks over a Claude Code skill (frontmatter, listing-budget cap, trigger-keyword preservation, line caps, broken internal refs, markdownlint, gotchas surface, evals presence) and a bundled evals.json schema for validation. Runs against any repo's skills directory via the convention-resolution ladder — no baked layout.
 
 ### Security

plugins/claude-ops/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "claude-ops",
-  "version": "0.9.0",
-  "description": "Claude Code operations toolkit. Five skills: observability (read locally captured telemetry — OTEL store, collector, hook-event JSONL, ccusage — with trend reports and store pruning), troubleshoot (search known Claude product GitHub bugs, check service health, maintain a persistent tracked-issue registry), changelog (ingest Claude Code changelog entries and integrate them into the current repo), plugins (bring a machine's plugin fleet current on demand — marketplace refresh, effective-scope updates including in-repo project/local installs, new-plugin install per policy, scope-divergence detection and explicit convergence), and a re-runnable setup action that settles where the troubleshooting registry lives. Plus a family of seven advisory *-audit telemetry-emitter hooks (API errors, config changes, instruction loads, permission denials, pre-compaction, skill usage, tool failures) that emit the shared hook-telemetry envelope, and a reference sink that maps envelopes into the hook-events.jsonl the observability skill reads.",
+  "version": "0.10.0",
+  "description": "Claude Code operations toolkit. Five skills: observability (read locally captured telemetry — OTEL store, collector, hook-event JSONL, ccusage — with trend reports and store pruning), known-issues (search known Claude product GitHub bugs, check service health, maintain a persistent tracked-issue registry), changelog (ingest Claude Code changelog entries and integrate them into the current repo), plugins (bring a machine's plugin fleet current on demand — marketplace refresh, effective-scope updates including in-repo project/local installs, new-plugin install per policy, scope-divergence detection and explicit convergence), and a re-runnable setup action that settles where the known-issues registry lives. Plus a family of seven advisory *-audit telemetry-emitter hooks (API errors, config changes, instruction loads, permission denials, pre-compaction, skill usage, tool failures) that emit the shared hook-telemetry envelope, and a reference sink that maps envelopes into the hook-events.jsonl the observability skill reads.",
   "author": {
     "name": "Melodic Software",
     "email": "info@melodicsoftware.com"
@@ -13,7 +13,7 @@
     "registry_dir": {
       "type": "string",
       "title": "Registry directory (project-relative)",
-      "description": "Optional contained project-relative directory holding the troubleshoot issue registry (registry.json). Absolute, drive, UNC, traversal, and escaping-symlink paths are invalid. Leave unset to use ${CLAUDE_PLUGIN_DATA}."
+      "description": "Optional contained project-relative directory holding the known-issues registry (registry.json). Absolute, drive, UNC, traversal, and escaping-symlink paths are invalid. Leave unset to use ${CLAUDE_PLUGIN_DATA}."
     },
     "skill_usage_dir": {
       "type": "string",

plugins/claude-ops/CHANGELOG.md

@@ -3,6 +3,16 @@
 All notable changes to the `claude-ops` plugin are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning.
 
+## [0.10.0]
+
+### Changed
+
+- **Breaking:** renamed the `troubleshoot` skill to `known-issues` (plugin ID `claude-ops` is
+  unchanged). Update any old invocations: `/claude-ops:troubleshoot` → `/claude-ops:known-issues`.
+  The skill looks up and tracks known upstream Claude product issues; it never diagnoses or fixes
+  local problems, so the old name over-promised. Behavior, actions, and the `registry_dir` option
+  are unchanged; the registry is now referred to as the known-issues registry.
+
 ## [0.9.0]
 
 ### Added

plugins/claude-ops/README.md

@@ -2,10 +2,10 @@
 
 A Claude Code plugin for running Claude Code well over time — one cohesive
 capability across five skills and a family of telemetry-emitter hooks.
-Observability reads what your sessions actually did, troubleshooting tracks what
+Observability reads what your sessions actually did, known-issues tracks what
 upstream has broken, changelog integration keeps your repo current with what
 upstream has shipped, the plugins skill keeps your own plugin fleet current, a
-re-runnable `setup` action settles where the troubleshooting registry lives,
+re-runnable `setup` action settles where the known-issues registry lives,
 and the `*-audit` hooks feed observability with per-hook execution telemetry
 Claude Code's native OTEL cannot see.
 
@@ -14,10 +14,10 @@ Claude Code's native OTEL cannot see.
 | Skill | What it does |
 |---|---|
 | `/claude-ops:observability` | Reads locally captured Claude Code telemetry — OTEL DuckDB store, machine-owned collector, optional Aspire dashboard, hook-event JSONL, ccusage — and renders cross-session trend reports (`session`/`day`/`week`/`month`/`since:`/`all` scopes). Read-only except the explicit `clean` action, which prunes the JSONL log and OTEL store by age. |
-| `/claude-ops:troubleshoot` | Searches known Claude product GitHub bugs before you build on a feature, checks service health and model quality, and maintains a persistent registry of tracked issues (what they block, workarounds, follow-ups when fixed). Actions: `status` (default), `search`, `check-all`, `scan`, `list`, `quality`, `create`. |
+| `/claude-ops:known-issues` | Searches known Claude product GitHub bugs before you build on a feature, checks service health and model quality, and maintains a persistent registry of tracked issues (what they block, workarounds, follow-ups when fixed). Actions: `status` (default), `search`, `check-all`, `scan`, `list`, `quality`, `create`. |
 | `/claude-ops:changelog` | Ingests Claude Code changelog entries and integrates them into the current repo: `fetch` (read-only display), `diff` (impact triage, no edits), `status` (applied versions from git history), and `apply` (full explore → research → interview → implement pipeline, explicit user intent only). |
 | `/claude-ops:plugins` | Brings a machine's plugin fleet current on demand: marketplace refresh, updates for the plugins that actually load (including in-repo project/local-scope installs), new-catalog-plugin install per policy, and scope-divergence detection. Actions: `sync` (default, CLI-mediated mutations only), `audit` (read-only dry run), `converge` (the one action that can touch a committed `.claude/settings.json` — previews and confirms per plugin first). |
-| `/claude-ops:setup` | Validates the troubleshooting-registry and skill-usage-log destinations, including path containment, and routes personal option changes through Claude Code's plugin configuration prompt. |
+| `/claude-ops:setup` | Validates the known-issues-registry and skill-usage-log destinations, including path containment, and routes personal option changes through Claude Code's plugin configuration prompt. |
 
 ## The audit hooks
 
@@ -102,7 +102,7 @@ your own repository's context:
   `<project-root>/.claude/observability/hook-events.jsonl` only when your own
   hooks emit it; every source degrades gracefully when absent.
 - **Persistent state** defaults to the plugin's own per-machine data directory
-  (`${CLAUDE_PLUGIN_DATA}`): the troubleshooting issue registry
+  (`${CLAUDE_PLUGIN_DATA}`): the known-issues registry
   (`registry.json`), `check-all` output, and `--write` observability reports.
   By default nothing is written into your repository. Opt in for the registry
   via the `registry_dir` option (see Configuration) to keep it git-tracked and
@@ -130,11 +130,11 @@ Three `userConfig` options:
   installing. The manifest schema has no `enum` type, so this validates in prose, not JSON Schema;
   any other value is treated as `ask`.
 - **`registry_dir`** (string, optional) — project-relative directory for the
-  troubleshoot issue registry (`registry.json`). Set it to keep the
+  known-issues registry (`registry.json`). Set it to keep the
   registry inside your repo (git-tracked, team-shared) instead of the
   per-machine plugin data directory; leave unset to use `${CLAUDE_PLUGIN_DATA}`.
   Absolute, drive-qualified, UNC, traversal, and escaping-symlink paths are
-  invalid; troubleshooting operations must stop and direct you to reconfigure
+  invalid; known-issues operations must stop and direct you to reconfigure
   rather than write outside the project.
 - **`skill_usage_dir`** (string, optional) — project-relative directory where
   `skill-usage-audit` writes its `skill-usage.jsonl` second store (the
@@ -149,7 +149,7 @@ configuration prompt; rerun setup afterward to verify the rendered value.
 Remaining variability is covered by the env vars above and conventional
 project-relative defaults; the bundled scripts make no outbound network calls
 except `gh`/`curl` reads of GitHub and Claude status pages in the
-troubleshooting skill.
+known-issues skill.
 
 ## License
 

plugins/claude-ops/skills/changelog/SKILL.md

@@ -16,7 +16,7 @@ Ingests Claude Code changelog entries and integrates them into the repo. Covers
 
 Distinct from:
 
-- `/troubleshoot` — tracks CC bugs/workarounds. This skill integrates CC feature changes into repo config/docs
+- `/known-issues` — tracks CC bugs/workarounds. This skill integrates CC feature changes into repo config/docs
 - Any release-triage automation the consumer runs (issue filing per release) — this skill IMPLEMENTS changes, holistically across a release
 
 ## Input modes

plugins/claude-ops/skills/troubleshoot/SKILL.md → plugins/claude-ops/skills/known-issues/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: troubleshoot
-description: "Troubleshoot Claude Code by searching known GitHub bugs, checking service health and model quality, and maintaining a persistent registry of tracked product issues. Use when: 'is this broken', 'known CC bugs', 'any workarounds', 'feature behaves unexpectedly', 'scan repo for issues', 'file a bug' — actions: status (default), search <feature>, check-all, scan, list, quality, create."
+name: known-issues
+description: "Looks up and tracks known Claude product issues — searches known GitHub bugs, checks service health and model quality, and maintains a persistent registry of tracked issues. Use when: 'is this broken', 'known CC bugs', 'troubleshoot Claude Code', 'any workarounds', 'feature behaves unexpectedly', 'scan repo for issues', 'file a bug' — actions: status (default), search <feature>, check-all, scan, list, quality, create."
 argument-hint: "<action> [args] — actions: status (default), search, check-all, scan, list, quality, create. e.g., 'search Stop hook', 'check-all', 'create bug \"title\"'"
 user-invocable: true
 disable-model-invocation: false

plugins/claude-ops/skills/troubleshoot/context/action-check-all.md → plugins/claude-ops/skills/known-issues/context/action-check-all.md

@@ -1,6 +1,6 @@
 # Action: `check-all`
 
-**Usage:** `/troubleshoot check-all`
+**Usage:** `/known-issues check-all`
 
 Check every registry issue against current GitHub status. Primary purpose: find issues RESOLVED since last check — unblocked work needing follow-up.
 

plugins/claude-ops/skills/troubleshoot/context/action-create.md → plugins/claude-ops/skills/known-issues/context/action-create.md

@@ -1,6 +1,6 @@
 # Action: `create`
 
-**Usage:** `/troubleshoot create <type> "<title>" [--repo <repo>]`
+**Usage:** `/known-issues create <type> "<title>" [--repo <repo>]`
 
 Draft and file GitHub issue on `anthropics/claude-code` (or specified repo) using official template format. Supports bug reports and feature requests.
 

plugins/claude-ops/skills/troubleshoot/context/action-list.md → plugins/claude-ops/skills/known-issues/context/action-list.md

@@ -1,6 +1,6 @@
 # Action: `list`
 
-**Usage:** `/troubleshoot list [--category <cat>] [--status <status>]`
+**Usage:** `/known-issues list [--category <cat>] [--status <status>]`
 
 Show all tracked issues from registry, grouped by status and category.
 

plugins/claude-ops/skills/troubleshoot/context/action-quality.md → plugins/claude-ops/skills/known-issues/context/action-quality.md

@@ -1,6 +1,6 @@
 # Action: `quality`
 
-**Usage:** `/troubleshoot quality`
+**Usage:** `/known-issues quality`
 
 Check current Claude model quality and service health from multiple sources. Use at start of work sessions or when you notice degraded performance.
 

plugins/claude-ops/skills/troubleshoot/context/action-scan.md → plugins/claude-ops/skills/known-issues/context/action-scan.md

@@ -1,6 +1,6 @@
 # Action: `scan`
 
-**Usage:** `/troubleshoot scan`
+**Usage:** `/known-issues scan`
 
 Grep entire repo for GitHub issue references (pattern: `#NNNNN` with `github.com/anthropics` or `github.com/microsoft/mcp` context) and add ones not in registry.
 

plugins/claude-ops/skills/troubleshoot/context/action-search.md → plugins/claude-ops/skills/known-issues/context/action-search.md

@@ -1,7 +1,7 @@
 # Action: `search`
 
-**Usage:** `/troubleshoot search <feature-name> [--repo <repo>] [--status] [--all]`
-**Also:** `/troubleshoot <feature-name>` (search is the default when args look like a feature name)
+**Usage:** `/known-issues search <feature-name> [--repo <repo>] [--status] [--all]`
+**Also:** `/known-issues <feature-name>` (search is the default when args look like a feature name)
 
 ## Flags
 

plugins/claude-ops/skills/troubleshoot/context/action-status.md → plugins/claude-ops/skills/known-issues/context/action-status.md

@@ -1,6 +1,6 @@
 # Action: `status`
 
-**Usage:** `/troubleshoot` (no args) or `/troubleshoot status`
+**Usage:** `/known-issues` (no args) or `/known-issues status`
 
 Quick health snapshot for proactive auto-invocation. Combines registry stats with a lightweight quality check.
 
@@ -16,8 +16,8 @@ Quick health snapshot for proactive auto-invocation. Combines registry stats wit
 Use the registry manager script for efficient stats (add `--data-dir` per the SKILL.md registry-location rule when a `registry_dir` is configured):
 
 ```bash
-python "${CLAUDE_PLUGIN_ROOT}/skills/troubleshoot/scripts/registry_manager.py" stats
-python "${CLAUDE_PLUGIN_ROOT}/skills/troubleshoot/scripts/registry_manager.py" list --stale 14
+python "${CLAUDE_PLUGIN_ROOT}/skills/known-issues/scripts/registry_manager.py" stats
+python "${CLAUDE_PLUGIN_ROOT}/skills/known-issues/scripts/registry_manager.py" list --stale 14
 ```
 
 **Step 2: Lightweight quality check** — fetch service health (fast):
@@ -43,7 +43,7 @@ Report overall status only (Operational / Degraded / Outage). Skip Marginlab for
 - **status.claude.com**: Operational / Degraded / Outage
 
 ### Recommendations
-- Run `/troubleshoot check-all` to refresh stale issues
-- Run `/troubleshoot quality` for full quality analysis
-- Run `/troubleshoot search <feature>` before building on a CC mechanism
+- Run `/known-issues check-all` to refresh stale issues
+- Run `/known-issues quality` for full quality analysis
+- Run `/known-issues search <feature>` before building on a CC mechanism
 ```

plugins/claude-ops/skills/troubleshoot/context/issue-templates.md → plugins/claude-ops/skills/known-issues/context/issue-templates.md

@@ -190,7 +190,7 @@ These fields can be pre-filled automatically:
 | Operating System | `uname -s` → Windows (MINGW/MSYS), macOS (Darwin), Linux |
 | Terminal/Shell | `$TERM_PROGRAM` or `$TERM` |
 | Platform | "Anthropic API" (default for this repo) |
-| Is a regression? | If issue found via `/troubleshoot search`, check registry for prior working state |
+| Is a regression? | If issue found via `/known-issues search`, check registry for prior working state |
 
 ## Contact links (non-issue options)