ZenUml/conf-app / .claude/skills/client-health
client-health
VerifiedRank active ZenUML Lite tenants on two independent 0-100 scores — Opportunity (upsell candidate) and Risk (disengagement) — to decide which clients to focus on. Use whenever the user asks "which clients should we focus on", "who's a good upsell candidate", "which tenants are at risk of churning", "health score", or wants a ranked list of Lite tenants by engagement strength or fragility. Scope: Lite only, active tenants only (macro_viewed > 0 in the scoring window). For a SINGLE named tenant's paid status/profile use the `tenant` skill instead; for lifetime revenue/renewals/overdue payers use `marketplace`.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.6 KB |
| scripts/health_score.py | script | 17.7 KB |
| scripts/percentile.py | script | 1.3 KB |
| scripts/test_health_score.py | script | 22.0 KB |
| scripts/test_percentile.py | script | 1.8 KB |
scripts/test_health_score.py
View on GitHub#!/usr/bin/env python3
"""Unit tests for health_score.py. No network, no credentials.
Run from the repo root:
python3 .claude/skills/client-health/scripts/test_health_score.py
or:
python3 -m unittest discover -s .claude/skills/client-health/scripts
"""
import datetime, json, os, sys, unittest
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
import health_score # noqa: E402
import mp_report # noqa: E402
import mp_query # noqa: E402
def license_rec(host, tier_users, company=None):
return {
"cloudSiteHostname": host,
"tier": f"{tier_users} Users",
"contactDetails": {"company": company or host.split(".")[0]},
}
class BuildFleetFromLicenses(unittest.TestCase):
def test_extracts_domain_seat_tier_and_company(self):
lic = [license_rec("acme.atlassian.net", 250, "Acme Corp")]
fleet = health_score.build_fleet_from_licenses(lic)
self.assertEqual(fleet["acme"]["seat_tier"], 250)
self.assertEqual(fleet["acme"]["company"], "Acme Corp")
def test_skips_records_with_unparseable_tier(self):
lic = [license_rec("acme.atlassian.net", 250),
{"cloudSiteHostname": "broken.atlassian.net", "tier": None,
"contactDetails": {}}]
fleet = health_score.build_fleet_from_licenses(lic)
self.assertIn("acme", fleet)
self.assertNotIn("broken", fleet)
def test_skips_records_with_no_hostname(self):
lic = [{"cloudSiteHostname": "", "tier": "10 Users", "contactDetails": {}}]
fleet = health_score.build_fleet_from_licenses(lic)
self.assertEqual(fleet, {})
def test_prefers_active_license_over_inactive_duplicate(self):
# inactive row (stale/cancelled) listed first, active row second —
# the active row's tier must win regardless of encounter order.
lic = [
{"cloudSiteHostname": "acme.atlassian.net", "tier": "10 Users",
"status": "inactive", "maintenanceEndDate": "2026-01-01",
"contactDetails": {"company": "Acme Old"}},
{"cloudSiteHostname": "acme.atlassian.net", "tier": "250 Users",
"status": "active", "maintenanceEndDate": "2026-06-01",
"contactDetails": {"company": "Acme"}},
]
fleet = health_score.build_fleet_from_licenses(lic)
self.assertEqual(fleet["acme"]["seat_tier"], 250)
def test_prefers_active_license_over_inactive_duplicate_reversed_order(self):
# same two records, active row listed FIRST this time — proves the
# preference isn't just "keep the first row I saw".
lic = [
{"cloudSiteHostname": "acme.atlassian.net", "tier": "250 Users",
"status": "active", "maintenanceEndDate": "2026-06-01",
"contactDetails": {"company": "Acme"}},
{"cloudSiteHostname": "acme.atlassian.net", "tier": "10 Users",
"status": "inactive", "maintenanceEndDate": "2026-01-01",
"contactDetails": {"company": "Acme Old"}},
]
fleet = health_score.build_fleet_from_licenses(lic)
self.assertEqual(fleet["acme"]["seat_tier"], 250)
def test_prefers_more_recent_maintenance_end_date_among_same_status(self):
lic = [
{"cloudSiteHostname": "acme.atlassian.net", "tier": "50 Users",
"status": "active", "maintenanceEndDate": "2025-01-01",
"contactDetails": {"company": "Acme"}},
{"cloudSiteHostname": "acme.atlassian.net", "tier": "250 Users",
"status": "active", "maintenanceEndDate": "2026-06-01",
"contactDetails": {"company": "Acme"}},
]
fleet = health_score.build_fleet_from_licenses(lic)
self.assertEqual(fleet["acme"]["seat_tier"], 250)
class ArrMonthly(unittest.TestCase):
def test_delegates_to_mp_pricing_band_table(self):
# 820 users: 100@0.44 + 150@0.33 + 570@0.11 = 44 + 49.5 + 62.7 = 156.2
self.assertAlmostEqual(health_score.arr_monthly(820), 156.2, places=2)
class BuildAndParseVolumeQuery(unittest.TestCase):
def test_query_contains_the_window_dates(self):
today = datetime.date(2026, 9, 4)
script = health_score.build_volume_query(days=90, today=today)
self.assertIn("2026-06-06", script) # today - 90 days
self.assertIn("2026-09-04", script) # today
def test_query_excludes_internal_domains_and_filters_lite(self):
script = health_score.build_volume_query()
self.assertIn("product_type", script)
self.assertIn("zenuml", script) # internal-domain exclude list present
# lite-prod is the internal Lite *production* site — the exact
# variant this script scores — so its absence is the most
# consequential gap in a stale exclude list (I3).
self.assertIn("lite-prod", script)
self.assertIn("asyncapi-stg", script)
self.assertIn("danshuitaihejie", script)
def test_parse_sums_usage_volume_and_paywall_friction(self):
today = datetime.date(2026, 9, 4)
rows = [
{"key": ["acme", "2026-09-01", "macro_viewed"], "value": 10},
{"key": ["acme", "2026-09-02", "macro_viewed"], "value": 5},
{"key": ["acme", "2026-09-02", "paywall_over_limit"], "value": 3},
]
parsed = health_score.parse_volume_rows(rows, today=today)
self.assertEqual(parsed["acme"]["usage_volume"], 15)
self.assertEqual(parsed["acme"]["paywall_friction"], 3)
def test_retired_block_events_are_not_paywall_friction(self):
# The editor block was switched off (shouldBlockActions is constant
# false), so paywall_triggered / paywall_blocked_* stopped arriving
# on 2026-09-11. Counting them fills a 90-day window with old data.
rows = [
{"key": ["acme", "2026-09-02", "macro_viewed"], "value": 5},
{"key": ["acme", "2026-09-02", "paywall_triggered"], "value": 2},
{"key": ["acme", "2026-09-02", "paywall_blocked_create"], "value": 1},
{"key": ["acme", "2026-09-02", "paywall_blocked_edit"], "value": 1},
]
parsed = health_score.parse_volume_rows(rows, today=datetime.date(2026, 9, 4))
self.assertEqual(parsed["acme"]["paywall_friction"], 0)
def test_volume_query_counts_gate_evaluations_on_over_limit_unpaid_spaces(self):
script = health_score.build_volume_query()
self.assertIn("paywall_gate_evaluated", health_score.VOLUME_EVENTS)
for retired in ("paywall_triggered", "paywall_blocked_create", "paywall_blocked_edit"):
self.assertNotIn(retired, script)
# A gate evaluation is friction when the gate fired, or when the space
# is over its limit, enforced and unpaid. Others are dropped.
self.assertEqual(health_score.is_paywall_friction(
{"gate_fired": True}), True)
cases = [
({"macro_count": 120, "macro_limit": 100, "css_enabled": True, "space_paid": False}, True),
({"macro_count": 100, "macro_limit": 100, "css_enabled": True, "space_paid": False}, True), # at the limit
({"macro_count": 99, "macro_limit": 100, "css_enabled": True, "space_paid": False}, False),
({"macro_count": 120, "macro_limit": 100, "css_enabled": True, "space_paid": True}, False), # space licence
({"macro_count": 120, "macro_limit": 100, "css_enabled": False, "space_paid": False}, False), # exempt site
({"macro_limit": 100, "css_enabled": True, "space_paid": False}, False), # count unknown
]
for props, want in cases:
self.assertEqual(health_score.is_paywall_friction({"gate_fired": False, **props}), want, props)
self.assertIn(health_score.PAYWALL_FRICTION_JS.strip(), script)
def test_parse_splits_recent_vs_prior_30_day_windows(self):
today = datetime.date(2026, 9, 4)
rows = [
{"key": ["acme", "2026-09-03", "macro_viewed"], "value": 10}, # recent (within last 30d)
{"key": ["acme", "2026-07-20", "macro_viewed"], "value": 4}, # prior (31-60 days back)
{"key": ["acme", "2026-06-10", "macro_viewed"], "value": 99}, # outside both windows (>60d back)
]
parsed = health_score.parse_volume_rows(rows, today=today)
self.assertEqual(parsed["acme"]["recent_views"], 10)
self.assertEqual(parsed["acme"]["prior_views"], 4)
def test_parse_tracks_the_most_recent_event_date(self):
today = datetime.date(2026, 9, 4)
rows = [
{"key": ["acme", "2026-08-01", "macro_viewed"], "value": 1},
{"key": ["acme", "2026-09-02", "macro_save_succeeded"], "value": 1},
]
parsed = health_score.parse_volume_rows(rows, today=today)
self.assertEqual(parsed["acme"]["last_event_date"], datetime.date(2026, 9, 2))
def test_parse_ignores_zero_count_rows_for_last_event_date(self):
today = datetime.date(2026, 9, 4)
rows = [{"key": ["acme", "2026-09-02", "macro_viewed"], "value": 0}]
parsed = health_score.parse_volume_rows(rows, today=today)
self.assertIsNone(parsed["acme"]["last_event_date"])
class BuildAndParseCreatorsQuery(unittest.TestCase):
def test_query_filters_to_create_events_only(self):
script = health_score.build_creators_query()
self.assertIn("macro_create_succeeded", script)
self.assertNotIn("macro_save_succeeded", script)
def test_parse_counts_distinct_users_per_domain(self):
rows = [
{"key": ["acme", "user-1"], "value": 3},
{"key": ["acme", "user-2"], "value": 1},
{"key": ["other", "user-1"], "value": 5},
]
parsed = health_score.parse_creators_rows(rows)
self.assertEqual(parsed["acme"], 2)
self.assertEqual(parsed["other"], 1)
class ComputeRawSignals(unittest.TestCase):
def setUp(self):
self.fleet = {
"acme": {"cloud_id": "c1", "seat_tier": 100, "company": "Acme"},
"quiet": {"cloud_id": "c2", "seat_tier": 100, "company": "Quiet Co"},
}
self.today = datetime.date(2026, 9, 4)
def test_excludes_domains_with_zero_usage_volume(self):
volume = {"acme": {"usage_volume": 10, "paywall_friction": 0,
"recent_views": 5, "prior_views": 5,
"last_event_date": self.today}}
raw = health_score.compute_raw_signals(self.fleet, volume, {}, today=self.today)
self.assertIn("acme", raw)
self.assertNotIn("quiet", raw) # not in `volume` at all -> inactive, excluded
def test_growth_trend_and_adoption_breadth(self):
volume = {"acme": {"usage_volume": 100, "paywall_friction": 2,
"recent_views": 60, "prior_views": 40,
"last_event_date": self.today}}
raw = health_score.compute_raw_signals(self.fleet, volume, {"acme": 20}, today=self.today)
self.assertAlmostEqual(raw["acme"]["growth_trend"], 0.5) # (60-40)/40
self.assertAlmostEqual(raw["acme"]["adoption_breadth"], 0.2) # 20/100
self.assertEqual(raw["acme"]["days_since_last_event"], 0)
def test_recency_days_since_last_event(self):
volume = {"acme": {"usage_volume": 5, "paywall_friction": 0,
"recent_views": 5, "prior_views": 0,
"last_event_date": datetime.date(2026, 8, 25)}}
raw = health_score.compute_raw_signals(self.fleet, volume, {}, today=self.today)
self.assertEqual(raw["acme"]["days_since_last_event"], 10)
class ScoreFleet(unittest.TestCase):
def test_broad_adopter_outranks_thin_adopter_on_opportunity_and_risk(self):
# Mirrors this session's tenant-a (broad) vs tenant-b (thin) finding:
# near-identical seat tier and usage volume, very different
# adoption breadth and growth.
raw = {
"broad": {"seat_tier": 800, "arr_monthly": 150.0, "adoption_breadth": 0.015,
"usage_volume": 3000, "growth_trend": 0.1, "paywall_friction": 0,
"days_since_last_event": 0, "unique_creators": 12},
"thin": {"seat_tier": 800, "arr_monthly": 150.0, "adoption_breadth": 0.005,
"usage_volume": 3000, "growth_trend": -0.3, "paywall_friction": 0,
"days_since_last_event": 5, "unique_creators": 4},
"small": {"seat_tier": 20, "arr_monthly": 8.8, "adoption_breadth": 0.01,
"usage_volume": 50, "growth_trend": 0.0, "paywall_friction": 0,
"days_since_last_event": 20, "unique_creators": 1},
}
scored = health_score.score_fleet(raw)
self.assertGreater(scored["broad"]["opportunity_score"], scored["thin"]["opportunity_score"])
self.assertGreater(scored["thin"]["risk_score"], scored["broad"]["risk_score"])
def test_exact_scores_on_broad_thin_small_fixture(self):
# Hand-computed expected values (spec's "full score computation on
# a fixture fleet with hand-computed expected ranks" test case).
# Independently verified by running score_fleet on this exact
# fixture before writing the assertions — see PR discussion.
raw = {
"broad": {"seat_tier": 800, "arr_monthly": 150.0, "adoption_breadth": 0.015,
"usage_volume": 3000, "growth_trend": 0.1, "paywall_friction": 0,
"days_since_last_event": 0, "unique_creators": 12},
"thin": {"seat_tier": 800, "arr_monthly": 150.0, "adoption_breadth": 0.005,
"usage_volume": 3000, "growth_trend": -0.3, "paywall_friction": 0,
"days_since_last_event": 5, "unique_creators": 4},
"small": {"seat_tier": 20, "arr_monthly": 8.8, "adoption_breadth": 0.01,
"usage_volume": 50, "growth_trend": 0.0, "paywall_friction": 0,
"days_since_last_event": 20, "unique_creators": 1},
}
scored = health_score.score_fleet(raw)
self.assertEqual(scored["broad"]["opportunity_score"], 70.0)
self.assertEqual(scored["broad"]["risk_score"], 16.7)
self.assertEqual(scored["thin"]["opportunity_score"], 43.3)
self.assertEqual(scored["thin"]["risk_score"], 72.2)
self.assertEqual(scored["small"]["opportunity_score"], 36.7)
self.assertEqual(scored["small"]["risk_score"], 61.1)
def test_size_value_averages_two_disagreeing_sub_percentiles(self):
# Spec's "size_value combination of two sub-percentiles" case.
# seat_tier and arr_monthly are set INDEPENDENTLY (not derived from
# each other via arr_monthly() / mp_pricing, which is monotonic in
# seats and would keep the two percentiles in lockstep) so their
# percentile ranks actively disagree per tenant: A ranks top on
# seat_tier (100 vs 10) but bottom on arr_monthly (10 vs 100), and
# vice versa for B. Every other signal is identical between A and
# B. If size_value used only one sub-percentile, A and B would
# score at opposite extremes; averaging the two disagreeing ranks
# instead makes size_value — and therefore opportunity_score —
# identical for both, which is what this test pins.
raw = {
"A": {"seat_tier": 100, "arr_monthly": 10.0, "adoption_breadth": 0.1,
"usage_volume": 500, "growth_trend": 0.2, "paywall_friction": 1,
"days_since_last_event": 2, "unique_creators": 5},
"B": {"seat_tier": 10, "arr_monthly": 100.0, "adoption_breadth": 0.1,
"usage_volume": 500, "growth_trend": 0.2, "paywall_friction": 1,
"days_since_last_event": 2, "unique_creators": 5},
}
scored = health_score.score_fleet(raw)
self.assertEqual(scored["A"]["opportunity_score"], 50.0)
self.assertEqual(scored["B"]["opportunity_score"], 50.0)
self.assertEqual(scored["A"]["opportunity_score"], scored["B"]["opportunity_score"])
def test_scores_are_bounded_0_to_100(self):
raw = {
"a": {"seat_tier": 10, "arr_monthly": 4.4, "adoption_breadth": 0.1,
"usage_volume": 5, "growth_trend": 0.0, "paywall_friction": 0,
"days_since_last_event": 1, "unique_creators": 1},
"b": {"seat_tier": 1000, "arr_monthly": 400.0, "adoption_breadth": 0.5,
"usage_volume": 5000, "growth_trend": 2.0, "paywall_friction": 10,
"days_since_last_event": 0, "unique_creators": 100},
}
scored = health_score.score_fleet(raw)
for s in scored.values():
self.assertGreaterEqual(s["opportunity_score"], 0)
self.assertLessEqual(s["opportunity_score"], 100)
self.assertGreaterEqual(s["risk_score"], 0)
self.assertLessEqual(s["risk_score"], 100)
class MainCli(unittest.TestCase):
"""Monkeypatches the two network-touching fetchers so main() runs with
zero credentials and zero network calls — same pattern
test_mp_report.py uses for its --app resolution tests."""
def setUp(self):
self.fleet = {
"broad": {"cloud_id": "c1", "seat_tier": 800, "company": "Broad Co"},
"thin": {"cloud_id": "c2", "seat_tier": 800, "company": "Thin Co"},
}
self.volume = {
"broad": {"usage_volume": 3000, "paywall_friction": 0,
"recent_views": 1600, "prior_views": 1400,
"last_event_date": datetime.date.today()},
"thin": {"usage_volume": 3000, "paywall_friction": 0,
"recent_views": 1000, "prior_views": 2000,
"last_event_date": datetime.date.today()},
}
self.creators = {"broad": 12, "thin": 4}
def _run_main(self, argv):
import contextlib, io
buf = io.StringIO()
err = io.StringIO()
old_argv = sys.argv
sys.argv = ["health_score.py"] + argv
health_score.fetch_lite_licenses = lambda auth: []
health_score.build_fleet_from_licenses = lambda lic: self.fleet
health_score.fetch_mixpanel_signals = lambda api_secret, days=90: (self.volume, self.creators)
mp_report.load_creds = lambda env_path: ("fake@example.com", "fake-token")
mp_query.load_api_secret = lambda: "fake-secret"
try:
with contextlib.redirect_stdout(buf), contextlib.redirect_stderr(err):
health_score.main()
finally:
sys.argv = old_argv
self.last_stderr = err.getvalue() # set even if main() raised (e.g. SystemExit)
return buf.getvalue()
def test_prints_both_tenants_sorted_by_opportunity_by_default(self):
out = self._run_main(["--top", "10"])
self.assertIn("broad", out)
self.assertIn("thin", out)
self.assertLess(out.index("broad"), out.index("thin")) # broad ranks first
def test_sort_by_risk_flag_reorders(self):
out = self._run_main(["--sort", "risk", "--top", "10"])
self.assertLess(out.index("thin"), out.index("broad")) # thin is riskier
def test_json_flag_produces_parseable_json(self):
out = self._run_main(["--json", "--top", "10"])
rows = json.loads(out)
domains = {r["domain"] for r in rows}
self.assertEqual(domains, {"broad", "thin"})
def test_days_below_60_errors_cleanly_instead_of_corrupting_growth_trend(self):
# I2: parse_volume_rows' fixed 30-vs-30-day split can never
# populate the "prior" window below a 60-day fetch, which silently
# inflated growth_trend before this fix. main() now rejects it via
# argparse (SystemExit(2), usage/error text on stderr) rather than
# scoring tenants with a corrupted signal.
with self.assertRaises(SystemExit) as cm:
self._run_main(["--days", "30"])
self.assertEqual(cm.exception.code, 2)
self.assertIn("--days must be >= 60", self.last_stderr)
class MainCliDomainMismatchWarning(unittest.TestCase):
"""I5: a domain with real Mixpanel activity but no matching Marketplace
Lite license must be skipped with a stderr warning, not silently
dropped — per the design doc's Edge cases section."""
def setUp(self):
self.fleet = {
"broad": {"cloud_id": "c1", "seat_tier": 800, "company": "Broad Co"},
}
today = datetime.date.today()
self.volume = {
"broad": {"usage_volume": 100, "paywall_friction": 0,
"recent_views": 60, "prior_views": 40, "last_event_date": today},
# has real usage but no license in `fleet` above -> should warn
"orphan": {"usage_volume": 50, "paywall_friction": 0,
"recent_views": 30, "prior_views": 20, "last_event_date": today},
# the shared Mixpanel "domain not captured" sentinel -> must NOT warn
"unknown_atlassian_domain": {"usage_volume": 999, "paywall_friction": 0,
"recent_views": 500, "prior_views": 400,
"last_event_date": today},
}
self.creators = {"broad": 12, "orphan": 3}
def _run_main(self, argv):
import contextlib, io
buf, err = io.StringIO(), io.StringIO()
old_argv = sys.argv
sys.argv = ["health_score.py"] + argv
health_score.fetch_lite_licenses = lambda auth: []
health_score.build_fleet_from_licenses = lambda lic: self.fleet
health_score.fetch_mixpanel_signals = lambda api_secret, days=90: (self.volume, self.creators)
mp_report.load_creds = lambda env_path: ("fake@example.com", "fake-token")
mp_query.load_api_secret = lambda: "fake-secret"
try:
with contextlib.redirect_stdout(buf), contextlib.redirect_stderr(err):
health_score.main()
finally:
sys.argv = old_argv
return buf.getvalue(), err.getvalue()
def test_warns_for_mismatched_domain_but_not_for_unknown_atlassian_domain(self):
_, err = self._run_main(["--top", "10"])
self.assertIn("orphan", err)
self.assertNotIn("unknown_atlassian_domain", err)
if __name__ == "__main__":
unittest.main()
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |