feat: track built-in command usage

[cbeaulieu-gt]

Summary

• parse manual root-session <command-name> entries while retaining only command names and timestamps
• classify commands from a dated official catalog, excluding bundled skills and workflows such as /doctor
• add invocation/session counts and an unclassified audit section to JSON output and the existing Skills dashboard tab
• document the privacy boundary and package the catalog in release wheels

Verification

• python -m pytest -q — 1011 passed, 2 skipped
• python -m ruff check .
• python -m ruff format --check .
• fresh-wheel install, catalog classification, and dashboard render smoke test
• independent code review: 0 Critical and 0 Important findings after fixes

Closes #298

Summary by CodeRabbit

• New Features

  • Added a Built-in Commands report to the Skills dashboard.
  • Shows command invocation and session totals, classifications, source information, and unclassified commands for auditability.
  • JSON dashboard output now includes command-usage statistics.
  • Command tracking reads arguments and surrounding prompt text transiently while parsing transcript JSON, but retains only command names and timestamps and never writes that text.

• Documentation

  • Updated documentation to explain command classification, exclusions, auditability, and data-retention limits.

🤖 Generated by Codex on behalf of @cbeaulieu-gt

[coderabbitai]

📝 Walkthrough

Walkthrough

The dashboard now extracts manual slash-command names from root transcripts, classifies them with a packaged catalog, aggregates counts by time window, exposes the data in JSON, and displays a Built-in Commands report in the Skills view. Command arguments and surrounding prompt text are excluded.

Changes

Manual command extraction

Layer / File(s)	Summary
Parse manual command records src/claude_prospector/models.py, src/claude_prospector/parser.py, tests/test_parser.py	Session records store manual command names and timestamps. Parsing excludes arguments, automatic events, duplicates, subagent commands, and invalid records.

Command classification

Layer / File(s)	Summary
Validate and load command catalog src/claude_prospector/builtin_commands.py, src/claude_prospector/data/claude-code-commands.json, pyproject.toml, tests/test_builtin_commands.py	A packaged catalog classifies built-ins, bundled skills, workflows, and unclassified commands. Validation and unavailable-catalog fallback are covered by tests.

Aggregation and dashboard data

Layer / File(s)	Summary
Aggregate and expose command usage src/claude_prospector/aggregator.py, src/claude_prospector/cli/dashboard.py, src/claude_prospector/renderer.py, tests/test_aggregator.py, tests/test_cli.py, tests/test_renderer.py, tests/test_phase2_shell.py, tests/fixtures/dashboard_snapshot_pre_refactor.json	Aggregation filters commands by date, counts invocations and sessions, and adds by_command_usage to CLI and embedded dashboard JSON.

Skills view report

Layer / File(s)	Summary
Render the Built-in Commands report src/claude_prospector/static/views/skills.js, tests/test_skills_view.py, README.md	The Skills view renders classified and unclassified commands, metadata, empty and unavailable states, and escaped command names. README documentation describes the data and privacy scope.

Sequence Diagram(s)

sequenceDiagram
  participant TranscriptParser
  participant Aggregator
  participant DashboardJSON
  participant SkillsView
  TranscriptParser->>Aggregator: provide manual command records
  Aggregator->>Aggregator: classify and count records
  Aggregator->>DashboardJSON: add by_command_usage
  DashboardJSON->>SkillsView: provide command usage data

Loading

Merge Risk: 🟡 Moderate · up to 33c8c

Command-usage reports can misclassify valid built-in aliases and count non-invocations, while the privacy documentation incorrectly states that surrounding transcript text is never collected. Correct these before relying on the new reporting and privacy guarantees.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes satisfy issue #298. They parse manual root-session commands, exclude automatic and non-built-in commands, use a documented catalog, report invocation and session counts, expose unclassifie…
Out of Scope Changes check	✅ Passed	The changes are within scope for issue #298. The catalog, packaging update, implementation, dashboard integration, documentation, and regression tests directly support built-in command tracking. No un…
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: tracking built-in command usage.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch feature-298-builtin-command-usage

---

_{Comment @coderabbitai help to get the list of available commands.}

[cbeaulieu-gt]

@coderabbitai Review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 3

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Team

Run ID: f39fdfe1-8b8d-42e9-a65b-beba975044fe

📥 Commits

Reviewing files that changed from the base of the PR and between 287c5c3 and 33c8cbe.

📒 Files selected for processing (18)

• README.md
• pyproject.toml
• src/claude_prospector/aggregator.py
• src/claude_prospector/builtin_commands.py
• src/claude_prospector/cli/dashboard.py
• src/claude_prospector/data/claude-code-commands.json
• src/claude_prospector/models.py
• src/claude_prospector/parser.py
• src/claude_prospector/renderer.py
• src/claude_prospector/static/views/skills.js
• tests/fixtures/dashboard_snapshot_pre_refactor.json
• tests/test_aggregator.py
• tests/test_builtin_commands.py
• tests/test_cli.py
• tests/test_parser.py
• tests/test_phase2_shell.py
• tests/test_renderer.py
• tests/test_skills_view.py

Included review availability: 9 reviews are currently available. Your included PR review attempts over the past 7 days set your current allowance at 10 reviews per hour.