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: "<status|search|check-all|scan|list|quality|create> [args]"
user-invocable: true
disable-model-invocation: false
shell: bash
metadata:
  workflow-stage: anytime
  summary: Look up and track known Claude product issues, health, and workarounds
---

**Arguments.** `<status|search|check-all|scan|list|quality|create> [args]`. Full form: <action> [args]. Actions: status (default), search, check-all, scan, list, quality, create. e.g., 'search Stop hook', 'check-all', 'create bug "title"'

## Pre-computed context

Claude Code version: !`claude --version 2>/dev/null || echo "unknown"`

## Variables

Arguments: `$ARGUMENTS`

## Purpose

Claude Code ships frequently. Features that worked last week may have new bugs today. This skill serves three purposes:

1. **Quick health check**. Snapshot of registry health and model quality (no args needed)
2. **Proactive search**. Find known bugs BEFORE you build on top of a feature
3. **Issue registry**. Maintain single source of truth for the Claude product GitHub issues you track, record what they block, and create follow-up work items when bugs are fixed

## Data Files

The issue registry (`registry.json`) persists in the **registry directory**. By default this is the
plugin's per-machine data directory (`${CLAUDE_PLUGIN_DATA}`, survives plugin updates). A consumer can
instead keep the registry inside their repository, git-tracked and team-shared, by setting the
`registry_dir` plugin option (personal user configuration).

**Registry location. Apply to EVERY `registry_manager.py` invocation:** the configured value is
`${user_config.registry_dir}`; the project root is `${CLAUDE_PROJECT_DIR}`.

- If `${user_config.registry_dir}` is a non-empty path → first require a contained
  project-relative value. Reject POSIX/rooted paths, Windows drive-qualified or drive-relative
  paths, UNC paths, any `..` segment with either separator, and any existing symlink path that
  resolves outside `${CLAUDE_PROJECT_DIR}`. If invalid, stop the registry action, report the
  configuration problem visibly, and direct `/harness-ops:setup`; do not join, normalize, create,
  or use the destination. If valid, pass
  `--data-dir "${CLAUDE_PROJECT_DIR}/${user_config.registry_dir}"`.
- If it is empty or still shows an unexpanded `${user_config.registry_dir}` token (option unset) → pass
  `--data-dir "${CLAUDE_PLUGIN_DATA}"`. The Bash tool's environment does not carry this plugin's
  `CLAUDE_PLUGIN_DATA`, and another plugin's SessionStart hook can export its own data directory
  under that name, so the script uses an inherited value only when it names harness-ops (Basis and
  recheck trigger: [Spoke paths](#spoke-paths)).

| File | Purpose | Who edits |
| --- | --- | --- |
| `<registry-dir>/registry.json` | All tracked Claude product GitHub issues with status, category, affected files, and what's blocked | Skill (on search/`scan --add`/check-all), via `scripts/registry_manager.py`. See the registry-location rule above |

Read `context/registry-schema.md` for the full `registry.json` schema and field enums.

## Action Router

Parse `$ARGUMENTS` to extract action (first token) and remaining arguments.

| Action | Description |
| --- | --- |
| `status` | Quick health summary. Registry stats + quality snapshot (DEFAULT when no args) |
| `search` | Search GitHub Issues for bugs on a specific feature (default when args look like a feature name) |
| `check-all` | Check ALL tracked registry issues. Find newly resolved ones, create follow-up TODOs |
| `scan` | Grep the current repo for GitHub issue references and report untracked ones (read-only); `scan --add` also registers them |
| `list` | Show all tracked issues grouped by status and category |
| `quality` | Full quality check. Benchmarks + status page + recent GitHub degradation reports |
| `create` | Draft and file GitHub issue on anthropics/claude-code using their template format |

**Smart routing:**

- No `$ARGUMENTS` → `status`
- `$ARGUMENTS` starts with action keyword → that action
- `$ARGUMENTS` doesn't start with action keyword → `search` with entire argument as feature name

---

## Action: `status`

Read `context/action-status.md` for full status process and output format. DEFAULT action when no args.

---

## Action: `search`

Read `context/action-search.md` for full search process, flags, and output format.

---

## Action: `check-all`

Read `context/action-check-all.md` for full check-all process and output format.

---

## Action: `scan`

Read `context/action-scan.md` for full scan process and output format.

---

## Action: `quality`

Read `context/action-quality.md` for full quality check process, sources, and output format.

---

## Action: `list`

Read `context/action-list.md` for full list process and output format.

---

## Action: `create`

Read `context/action-create.md` for full issue creation process, mandatory gates, and safety rules.

---

## Repos Reference

| Product | Repo | When to search |
|---------|------|----------------|
| Claude Code | `anthropics/claude-code` | Default. Hooks, skills, settings, plugins, tools |
| Python SDK | `anthropics/anthropic-sdk-python` | Python API client issues |
| TypeScript SDK | `anthropics/anthropic-sdk-typescript` | Node.js API client issues |
| C# SDK | `anthropics/anthropic-sdk-csharp` | .NET API client issues |
| MCP Protocol | `modelcontextprotocol/python-sdk` | MCP server/client issues |
| Azure MCP | `microsoft/mcp` | Azure MCP server issues |

## Integration Points

### With your work-item tracker

- `check-all` proposes follow-up work items for resolved issues (file them with whatever
  tracker the consumer project uses, e.g. `gh issue create`, after user confirmation)
- `search` suggests monitoring items for open issues worth watching

### With the consumer project's workarounds docs

If the consumer project documents Claude Code quirks/workarounds (e.g. in `CLAUDE.md` or a
rules file), cross-reference: `search` checks findings against it, `scan` surfaces documented
issues not yet in the registry, and a resolved issue's follow-up TODO includes cleaning up the
now-obsolete workaround. Skip silently when no such doc exists.

### With plan review

When stress-testing a plan that builds on a Claude Code mechanism, run `search` for that
mechanism first. Known bugs reshape plans cheaply before implementation.

### With `/bugs:write` (if installed)

For bugs in YOUR code (not Claude Code itself), use the `bugs` plugin's skill instead;
without it, write up the defect manually. This skill covers Claude product issues only.

## Spoke paths

The `context/` files write this skill's directory as `<skill-dir>`, which is `${CLAUDE_SKILL_DIR}`.
Put that path in place of the placeholder before running a command or writing it into a brief. Those
files arrive through the Read tool as plain bytes, so a `${…}` token in them would reach the Bash
tool unsubstituted, and the Bash tool's environment has no `CLAUDE_SKILL_DIR` to expand it from.
The same table says the Bash tool's environment does not receive `CLAUDE_PLUGIN_DATA`, which the
registry-location rule relies on. Basis: the plugins reference,
<https://code.claude.com/docs/en/plugins-reference#where-each-variable-resolves>, verified
2026-10-03; recheck when that table adds supporting files to where a `${…}` reference resolves, or
lists the Bash tool among the processes that receive the variables.

## What This Skill Does NOT Do

- **Does not read local telemetry**. OTEL store, collector, hooks, ccusage → invoke `/harness-ops:observability` via the Skill tool
- **Does not fix bugs**. Reports and tracks them
- **Does not test features**. Searches for KNOWN issues
- **Issue creation requires explicit confirmation**. `create` action always shows draft first, never auto-files
- **Does not monitor continuously**. Re-run `check-all` periodically (e.g. from a recurring work item or schedule)