cleanmatic:telemetry
Plain-Vietnamese read on how the PO's skills are actually used + whether their scripts/subagents are healthy + a thin internal-quality proxy (did validate pass). Runs read-only lenses over local telemetry (invocations, sessions, script runs, subagent outcomes, memory) and narrates them honestly — usage & health, NOT market effectiveness. Outputs ascii/markdown/mermaid/json.
- License 许可
- AGPL-3.0
- 最近更新
- 2026-07-21
- Stars
- ★ 17
- Forks
- 9
01 前言 Front Matter
- name
- cleanmatic:telemetry
- category
- observability
- keywords
- [ "telemetry", "usage", "health", "skills", "tokens", "sessions", "reliability", "subagents", "memory", "validate", "vietnamese", "dashboard", "analytics" ]
- metadata
- { "author": "cleanmatic", "version": "1.1.1" }
- description
- Plain-Vietnamese read on how the PO's skills are actually used + whether their scripts/subagents are healthy + a thin internal-quality proxy (did validate pass). Runs read-only lenses over local telemetry (invocations, sessions, script runs, subagent outcomes, memory) and narrates them honestly — usage & health, NOT market effectiveness. Outputs ascii/markdown/mermaid/json.
- when_to_use
- When the (non-technical) product owner asks how their skills are being used, which scripts error or run slow, whether subagents succeed, whether memory is tidy, or whether the last spec validate passed — and wants it explained in plain Vietnamese, not raw logs.
- argument-hint
- [--lens usage|session|health|reliability|workflow|validate|memory|product_memory|artifact_heat|forensics|all] [--format ascii|md|mermaid|json] [--days N] [--top N] [--lang vi|en]
- user-invocable
- true
02 资源文件 53
- 参考文档CHANGELOG.md5.3 KB
- 参考文档data/skill-chains.yaml1.2 KB
- 参考文档GUIDE-EN.md15.8 KB
- 参考文档GUIDE-VI.md17.2 KB
- 参考文档README.md17.0 KB
- 参考文档references/narration-contract.md3.7 KB
- 脚本scripts/analyze_telemetry.py7.6 KB
- 脚本scripts/catalog.py4.0 KB
- 脚本scripts/formatters.py3.3 KB
- 脚本scripts/harvester.py5.9 KB
- 脚本scripts/lens_artifact_heat.py2.4 KB
- 脚本scripts/lens_forensics.py3.8 KB
- 脚本scripts/lens_health.py2.1 KB
- 脚本scripts/lens_memory_health.py5.4 KB
- 脚本scripts/lens_product_memory.py3.6 KB
- 脚本scripts/lens_reliability.py2.2 KB
- 脚本scripts/lens_session_shape.py2.1 KB
- 脚本scripts/lens_usage_tokens.py5.5 KB
- 脚本scripts/lens_validate_proxy.py3.8 KB
- 脚本scripts/lens_workflow_chains.py5.1 KB
- 脚本scripts/register_telemetry_hooks.py11.1 KB
- 脚本scripts/telemetry_paths.py9.4 KB
- 脚本scripts/telemetry_render.py29.2 KB
- 脚本scripts/tests/fixtures/memory/good-fact.md222 B
- 脚本scripts/tests/fixtures/memory/MEMORY.md164 B
- 脚本scripts/tests/fixtures/memory/orphan-fact.md204 B
- 脚本scripts/tests/fixtures/sessions/sessB.jsonl839 B
- 脚本scripts/tests/fixtures/telemetry/hook-telemetry.jsonl493 B
- 脚本scripts/tests/fixtures/telemetry/invocations.jsonl591 B
- 脚本scripts/tests/fixtures/telemetry/sessions.jsonl420 B
- 脚本scripts/tests/fixtures/telemetry/subagent-outcomes.jsonl321 B
- 脚本scripts/tests/fixtures/telemetry/unknown-stray.jsonl93 B
- 脚本scripts/tests/test_analyze_telemetry_cli.py8.7 KB
- 脚本scripts/tests/test_catalog.py2.6 KB
- 脚本scripts/tests/test_fixtures_sane.py2.5 KB
- 脚本scripts/tests/test_formatters.py2.3 KB
- 脚本scripts/tests/test_harvester.py11.9 KB
- 脚本scripts/tests/test_lens_artifact_heat.py6.2 KB
- 脚本scripts/tests/test_lens_forensics.py1.5 KB
- 脚本scripts/tests/test_lens_health.py2.0 KB
- 脚本scripts/tests/test_lens_memory_health.py2.3 KB
- 脚本scripts/tests/test_lens_product_memory.py3.5 KB
- 脚本scripts/tests/test_lens_reliability.py1.5 KB
- 脚本scripts/tests/test_lens_session_shape.py1.7 KB
- 脚本scripts/tests/test_lens_usage_tokens.py3.5 KB
- 脚本scripts/tests/test_lens_validate_proxy.py3.8 KB
- 脚本scripts/tests/test_lens_workflow_chains.py3.7 KB
- 脚本scripts/tests/test_low_volume_gate.py1016 B
- 脚本scripts/tests/test_register_new_hooks.py4.8 KB
- 脚本scripts/tests/test_register_telemetry_hooks.py9.9 KB
- 脚本scripts/tests/test_telemetry_paths_helpers.py2.6 KB
- 脚本scripts/tests/test_telemetry_paths.py9.1 KB
- 脚本scripts/tests/test_telemetry_render.py6.8 KB
03 SKILL.md 正文
cleanmatic:telemetry — Usage & Health (Mức dùng & Sức khỏe)
A read-only skill that tells the product owner, in plain Vietnamese, three things about their own tooling:
- Mức dùng (Usage) — which skills get used (and how often), token weight per skill, and which skills are never touched.
- Sức khỏe (Health) — which scripts error or run slow (approx), whether subagents succeed/fail, whether memory is tidy.
- Một tín hiệu chất lượng nội bộ (a thin internal-quality proxy) — after a
product-specrun, didvalidatepass.
Honest framing — this is "mức dùng & sức khỏe", NOT "hiệu quả". It measures whether the machinery runs, never whether the product wins in the market. (Product-outcome tracking shipped separately as product-spec --learn, but even that records PO-declared outcomes vs goals offline — still NOT a market-effectiveness metric.) The narration MUST keep that line bright (see the honesty gate below).
What this is NOT
- Not a market/user-outcome metric. The validate proxy = "spec is well-formed", not "users adopted it". (PO-declared outcome tracking lives in
product-spec --learn; this skill does not read it.) - Not a writer — it never edits specs, code, the catalog, or memory. No
--apply, no fixes. - Not billing-exact — token attribution and
msdurations are directional/approx. - Not a CI gate — opinion-free numbers for the PO to read, nothing blocks on it.
How it runs (deterministic gather → LLM narrates)
The split both repos follow: a script gathers (deterministic, never judges), the skill narrates (judges, in VI). The skill NEVER recomputes a number — it narrates the script's dict.
# Recipient bundle: system python3 with PyYAML (the bundle's single runtime dep, shipped via product-spec).
python3 ./.claude/skills/telemetry/scripts/analyze_telemetry.py \
--lens all --format ascii [--days 30] [--top 10]
# In the cleanmatic dev repo, use the shared venv: ./.claude/skills/.venv/bin/python3 …
Default behaviour when the PO invokes /cleanmatic:telemetry:
- Run
analyze_telemetry.py --lens all --format ascii. - Read the aggregates; narrate in Vietnamese (default). Switch to English with
--lang en(the script also localizes its fixed labels) or just "in English". - Lead with the honesty gate; recommendations are gợi ý (suggestions) only.
Pass-through flags: --lens <name>, --format md|mermaid|json, --days N, --top N, --lang vi|en (fixed-label language, vi default), --session <id> / --all-sessions (forensics). Runs under system python3; needs PyYAML (the bundle's single runtime dependency, shipped with product-spec).
Lenses
--lens |
Reads (sink) | Surfaces |
|---|---|---|
usage |
invocations.jsonl + transcripts |
invocation counts, per-skill tokens (approx), never-used catalog |
session |
sessions.jsonl |
session count, avg/median duration, files, subagents, skill co-occurrence |
health |
hook-telemetry.jsonl |
per-script runs/errors/error-rate + avg ms (approx) |
reliability |
subagent-outcomes.jsonl |
subagent success / api_error / timeout / blocked / unknown per type |
workflow |
invocations.jsonl + data/skill-chains.yaml |
actual skill chains vs declared chains; deviations |
validate |
last_validated.json + hook-telemetry |
validate-pass proxy (internal quality, NOT market outcome) |
memory |
~/.claude/projects/<root>/memory/ |
orphans, dead index entries, broken [[links]], staleness (read-only) |
product_memory |
docs/product/.memory/ |
spec-store health: last-validated age, missing state files, critique-cache size (read-only) |
artifact_heat |
artifact-events.jsonl |
artifact-edit frequency: most-edited spec artifacts (heat ranking), within --days window |
forensics |
session transcript JSONL | one session reconstructed (skills/tools/tokens/files/duration) |
all |
the above (minus forensics) | the dashboard-lite the PO reads first |
Low-volume gate (chưa đủ dữ liệu)
Below ~5 data points a lens shows raw counts + "chưa đủ dữ liệu" and suppresses recommendations. On a thin/new repo most lenses WILL be gated — say so plainly; do not invent trends.
Narration & honesty gate (mandatory)
Detailed rubric: references/narration-contract.md. The non-negotiable parts:
- Separate MEASURED from NOT-MEASURED. Every report MUST end with a section "Cái này KHÔNG đo được" naming at minimum: market/user outcome (this skill measures usage/health, not market effectiveness); plus any lens that is empty/gated on current data → call it "chưa đủ dữ liệu", never spin it.
- Approx is approx. Token weight,
ms, andexitare inferred/directional — say "ước lượng", never present them as exact. - Suggestions, not verdicts. Phrase any action as a gợi ý the PO may ignore; the skill has no authority to prune skills, edit memory, or change scope.
- VI is native-quality — correct diacritics, natural register for a non-technical owner; numbers stay numbers, skill ids stay ascii.
Hook config & crash log
The 7 project Python hooks (5 telemetry + 2 enforcement) share one runtime,
.claude/hooks/hook_runtime.py, and one per-hook on/off file,
.claude/hooks/product-spec-hooks.json (key = the hook's filename stem):
| Hook stem (key) | Kind | Default when key missing |
|---|---|---|
mark_bash_start |
telemetry | enabled |
track_skill_invocation |
telemetry | enabled (one key gates BOTH its registrations: PreToolUse:Skill + UserPromptExpansion) |
track_script_execution |
telemetry | enabled |
track_subagent_outcome |
telemetry | enabled |
emit_session_summary |
telemetry | enabled |
memory_gap_hook |
enforcement | disabled |
product_spec_critique_nudge |
enforcement | disabled |
- Asymmetry (by design): a missing telemetry key defaults ON; a missing
enforcement key defaults OFF — a blocking hook must never be fallback-enabled.
An explicit
true/falsealways wins. Set a keyfalseto no-op that hook on its next invocation (each hook is a fresh process). - Enabling enforcement:
product-spec/install.sh --memory-hookandproduct-spec-critique/install.sh --critique-hookflip the respective key totrue. The hooks are already wired into Stop by the bundle installer; the flag is what activates them. mark_bash_start⇒ms: keep it enabled for per-script wall-clockms(and the health lens'savg_ms). Disabled → the health lens degradesavg_msto—(no crash).- Global kill-switch:
CK_TELEMETRY_DISABLED=1disables all telemetry hooks regardless of config (enforcement hooks are unaffected by it). - Crash log: a swallowed hook exception leaves one line in
.claude/hooks/.logs/hook-crashes.log(UTC ts, hook, exception type/message — never the stdin payload). Always-on; disable withCK_HOOK_AUDIT_DISABLED=1. The log is gitignored and excluded from the bundle.
Boundaries
- Read-only. No edits to spec/code/catalog/memory; no network; venv-run.
- GATE-NEVER-ASSUME / GATE-NO-SILENT-REVERSAL: not applicable in the usual sense (nothing is written/approved), but the skill still never fabricates a metric — an absent signal is reported as absent.
- Deferred capabilities (NOT in this skill): rich crash-log
errors.jsonl(can't instrument shipped scripts), HTML output, and market-outcome measurement (PO-declared outcome tracking lives inproduct-spec --learn, offline; true market effectiveness stays out of scope). SeeBACKLOG.md.
CHANGELOG
See CHANGELOG.md.
04 同仓库更多 Skills
cleanmatic:telemetry
x
cleanmatic:release
x
cleanmatic:product-spec
x
cleanmatic:product-spec-critique
x
cleanmatic:release
Cut a versioned release of the product-spec bundle: pack opt-in .claude/ artifacts into a deterministic tar.gz AND manage the root CHANGELOG.md release lifecycle (lock [Unreleased] → [X.Y.Z], bump manifest, hand the owner the tag push that fires release CI). Manifest-first selection; multiplatform recipient installer.
cleanmatic:product-spec
Interview-driven product spec hierarchy (Vision/BRD/PRD/Epic/Story) with traceability, validation, and visualization for product owners. Use when a non-technical PO needs to capture, structure, validate, or visualize product requirements without writing code.