Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

fix(telemetry): classify CLI usage errors separately from failures (#907)

Raghav Chamadiyae10858004322
diff --git a/docs/TELEMETRY.md b/docs/TELEMETRY.md
index ef14bc4e6..b525b1885 100644
--- a/docs/TELEMETRY.md
+++ b/docs/TELEMETRY.md
@@ -44,7 +44,7 @@ Every event, whatever its type, carries the same anonymous envelope:
| `properties.command` | `init`, `update`, `health` | Which command ran |
| `properties.subcommand` | `decision.add`, `telemetry.status` | A known subcommand name only |
| `properties.flags` | `["--resume", "--provider"]` | Option **names only**, never values |
-| `properties.status` | `ok` / `error` / `interrupted` | Success, failure, or user-cancelled (Ctrl-C) |
+| `properties.status` | `ok` / `error` / `usage_error` / `interrupted` | Success, failure, a mis-invocation (bad/unknown flag), or user-cancelled (Ctrl-C) |
| `properties.error_type` | `LLMProviderError` | Exception **class name only** |
| `properties.duration_ms` | `71840` | Performance in the wild |
diff --git a/packages/cli/src/repowise/cli/_instrumented_group.py b/packages/cli/src/repowise/cli/_instrumented_group.py
index e00035a06..bf907c978 100644
--- a/packages/cli/src/repowise/cli/_instrumented_group.py
+++ b/packages/cli/src/repowise/cli/_instrumented_group.py
@@ -87,6 +87,15 @@ class InstrumentedGroup(click.Group):
# counting that as "error" made success rates uninterpretable.
status = "interrupted"
raise
+ except click.UsageError as exc:
+ # Bad/unknown option, missing or malformed argument: the user
+ # mis-invoked the command (a typo, a wrong flag), not a product
+ # failure. Kept out of the ``error`` bucket so the real crash rate
+ # is readable — a UsageError subclasses ClickException, so this
+ # branch must sit *before* the ClickException one below.
+ status = "usage_error"
+ error_type = type(exc).__name__ # class name only, never the message
+ raise
except click.ClickException as exc:
status = "error"
error_type = type(exc).__name__ # class name only, never the message
diff --git a/packages/cli/src/repowise/cli/platform/telemetry/events.py b/packages/cli/src/repowise/cli/platform/telemetry/events.py
index 4da9ed520..fbcb038b9 100644
--- a/packages/cli/src/repowise/cli/platform/telemetry/events.py
+++ b/packages/cli/src/repowise/cli/platform/telemetry/events.py
@@ -60,7 +60,7 @@ class CommandRunEvent(TelemetryEvent):
command: str
subcommand: str | None = None
flags: list[str] = field(default_factory=list)
- status: str = "ok" # "ok" | "error"
+ status: str = "ok" # "ok" | "error" | "interrupted" | "usage_error"
error_type: str | None = None # exception class name only, no message
duration_ms: int = 0
# Open extension point for command-specific anonymous fields (bucketed
diff --git a/tests/unit/cli/test_telemetry.py b/tests/unit/cli/test_telemetry.py
index b669af804..6600b5090 100644
--- a/tests/unit/cli/test_telemetry.py
+++ b/tests/unit/cli/test_telemetry.py
@@ -261,6 +261,29 @@ class TestOutcomeClassification:
rec = self._run(monkeypatch, body)
assert rec and rec[0]["properties"]["status"] == "error"
+ def test_usage_error_is_not_error(self, monkeypatch: pytest.MonkeyPatch):
+ # A bad/unknown flag is the user mis-invoking the command, not a
+ # product failure — it must not inflate the error rate.
+ import click
+
+ def body() -> None:
+ raise click.NoSuchOption("--bogus")
+
+ rec = self._run(monkeypatch, body)
+ assert rec and rec[0]["properties"]["status"] == "usage_error"
+ assert rec[0]["properties"]["error_type"] == "NoSuchOption"
+
+ def test_app_guard_stays_error(self, monkeypatch: pytest.MonkeyPatch):
+ # A plain ClickException (e.g. "run `repowise init` first") is still a
+ # real "could not proceed" outcome and stays in the error bucket.
+ import click
+
+ def body() -> None:
+ raise click.ClickException("no index found")
+
+ rec = self._run(monkeypatch, body)
+ assert rec and rec[0]["properties"]["status"] == "error"
+
def test_command_outcome_rides_the_event(self, monkeypatch: pytest.MonkeyPatch):
from repowise.cli.platform import telemetry