From claude-wayfinder
Reports the deterministic-dispatch router's health — CI invariants, runtime telemetry, drift events, and catalog state. Wraps `claude-wayfinder health --report` and adds an Analysis section (drill-down on FAIL'ing or near-threshold metrics) plus an extended Notable Findings section (top dispatched agents/skills, catalog freshness). Trigger phrases: "/router-health", "router health", "dispatch health", "router status", "is the router healthy", "router metrics", "show router stats", "router report", "check the router", "router drift".
How this skill is triggered — by the user, by Claude, or both
Slash command
/claude-wayfinder:router-healthThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
You are reporting on the health of the deterministic-dispatch router. This is
You are reporting on the health of the deterministic-dispatch router. This is a read-only skill — never mutate state, logs, or the catalog.
python -m claude_wayfinder health --report.dispatch-log.jsonl (top agents, top skills, catalog
freshness) that complement the script's built-in Notable Findings.If invoked with --brief, skip step 2 and produce only Analysis + extended
Notable Findings. Useful for mid-session quick checks where the user does
not need the full report.
The script (claude_wayfinder._health.main) resolves each path argument via
env var override or ~/.claude/... home-dir default (Issue #262). Explicit
flags always win; passing no flag is equivalent to the default shown below.
| Argument | Env var override | Default (when env var absent) |
|---|---|---|
--drift-log | $ROUTER_DRIFT_PATH | ~/.claude/state/router-drift.jsonl |
--dispatch-log | $DISPATCH_LOG | ~/.claude/state/dispatch-log.jsonl |
--catalog-path | $DISPATCH_CATALOG_PATH | (omit; catalog section will be empty) |
--skills-dir | $ROUTER_SKILLS_DIR | ~/.claude/skills |
--agents-dir | $ROUTER_AGENTS_DIR | ~/.claude/agents |
--plugin-overrides-dir | $ROUTER_PLUGIN_OVERRIDES_DIR | ~/.claude/triggers |
Absent log files are treated as empty (telemetry sections render with zero events). Missing skills/agents/overrides directories produce a FAIL on the corresponding CI invariants, which is the correct signal.
Note: --drift-log uses $ROUTER_DRIFT_PATH (matching
scripts/analyze-drift-causes.py), not $ROUTER_DRIFT_LOG. Both tools
resolve the drift log from the same env var so overriding one overrides both.
Use the plugin-installed claude-wayfinder package via python -m. This
assumes the plugin venv's python is on $PATH (the standard setup after
/setup-wayfinder). If the user's shell does not have the venv activated,
substitute the absolute interpreter path:
${CLAUDE_PLUGIN_DATA}/venv/bin/python (POSIX) or
${CLAUDE_PLUGIN_DATA}/venv/Scripts/python.exe (Windows).
Bare invocation uses the home-dir defaults automatically:
python -m claude_wayfinder health --report
Override individual paths via env vars when needed:
ROUTER_DRIFT_PATH=/custom/drift.jsonl python -m claude_wayfinder health --report
Or pass explicit flags (these override both env vars and defaults):
python -m claude_wayfinder health --report \
--drift-log /path/to/router-drift.jsonl \
--dispatch-log /path/to/dispatch-log.jsonl \
--skills-dir /path/to/skills \
--agents-dir /path/to/agents \
--plugin-overrides-dir /path/to/triggers
--catalog-path is omitted intentionally — the script falls back to
$DISPATCH_CATALOG_PATH when no flag is passed.
If --brief was passed by the user, capture the output but do not print it
verbatim — only use it as input to Step 2.
Unless --brief was passed, emit the captured markdown unchanged. Begin
your response with the report.
The script already emits an ACTION REQUIRED block for FAIL'ing CI
invariants and a THRESHOLD BREACH block for FAIL'ing runtime telemetry.
The Analysis section adds warning-zone drill-down for metrics that pass
today but are within 80% of the FAIL threshold, plus drift-event
correlation.
Parse each row of the CI Invariants and Runtime Telemetry tables for
the Status column. For every row whose status is FAIL OR is within
80% of the FAIL threshold, produce a sub-bullet under the Analysis
section explaining the most likely driver.
| Metric | Healthy direction | Warning zone (>80% toward FAIL) |
|---|---|---|
| Dispatch invocation rate | ≥ 80% | between 80% and 84% |
| Bypass rate | ≤ 10% | between 8% and 10% |
| Advisory override rate | ≤ 30% | between 24% and 30% |
| Catalog availability | = 100% | any sub-100% reading is already a FAIL |
| Catalog stability | identical bytes | byte-difference is FAIL outright |
| Schema validation | exit 0, 0 fatal | any fatal entry is FAIL outright |
| Trigger firing accuracy | 10/10 smoke tests | <10/10 is FAIL outright |
Drift events come in two shapes — your queries must handle both:
{"type": "router_drift", "category": "bypass" | "advisory_override" | ...}{"type": "self_handle_unaided_invocation", "count": N} (no category field)Use e.get("category") or e.get("type") as the canonical event-kind
discriminator in all log queries. Treating category as required will
crash on type-tagged events.
For Bypass rate FAIL or warning, use the drill subcommand:
python -m claude_wayfinder health drill --metric bypass --window 30d
The --drift-log flag is optional; the CLI reads from
$ROUTER_DRIFT_PATH or ~/.claude/state/router-drift.jsonl by default.
Report the daily distribution and top-bypassing sessions from the output.
If 5+ events come from the same session, that session is the likely outlier —
flag it. Drift events do NOT carry subagent_type; to identify which agent
was bypassed, correlate by session_id with dispatch-log.jsonl.
For Advisory override rate FAIL or warning, use the drill subcommand:
python -m claude_wayfinder health drill --metric advisory-override --window 30d
Report the top-3 overriding sessions from the output. Correlate with
dispatch-log.jsonl to see which agent the router chose instead of the
matcher's advice.
For Dispatch invocation rate FAIL or warning, this is the rate at
which the router invoked the dispatch skill before delegating. Low rate
means the router is routing on LLM judgment instead of deterministic
matching. Sample 5 recent agent_dispatch events from
dispatch-log.jsonl and check whether each was preceded by a
dispatch_invocation for the same session within ~30 seconds.
For Catalog availability FAIL, any catalog_degraded_session event is
immediate action. Print the most recent ones in full (timestamp,
session_id, full event payload) and recommend re-running the catalog
generator (/refresh-catalog or claude-wayfinder catalog build) and
inspecting the build log.
For Catalog stability FAIL, the script ran the catalog builder twice and got byte-different output — the generator is non-deterministic. Re-run by hand and diff. Common causes: dict iteration order, timestamp embedding, unsorted set serialization.
After the per-metric drill-down, surface the 5 most recent drift events:
python -m claude_wayfinder health drill --metric recent-drift --limit 5
If there are zero recent events, say so explicitly — that is a positive signal worth surfacing.
The script's built-in ## Notable Findings section reports plugin entry
counts. Extend it with:
python -m claude_wayfinder health top --kind agents --window 30d --limit 3
The --dispatch-log flag is optional; the CLI reads from $DISPATCH_LOG
or ~/.claude/state/dispatch-log.jsonl by default.
Flag if any one agent dominates above 60% — that may indicate the router is over-delegating to a single specialist, or that the user's workload is genuinely concentrated.
python -m claude_wayfinder health top --kind skills --window 30d --limit 3
The top skill being dispatch itself is expected; if any other skill
dominates dispatch's count, that is notable.
self_handle_unaided rate (catalog coverage signal)The dispatch matcher returns self_handle_unaided when the input has
sufficient density (≥ 2 feature dimensions) but no specialist scored. A
rising rate suggests catalog coverage gaps.
For now, since dispatch-log.jsonl does not directly tag
self_handle_unaided, report this as best-effort by counting
agent_dispatch events with agent == "general-purpose" and an empty
skills_in_prompt array — those are the closest live proxy. Caveat the
metric explicitly when reporting it.
python -m claude_wayfinder health catalog-status
This reports plugin skill / agent entry counts and routable-agent count. Flag any unexpected zeros (e.g. zero routable agents when plugin-override entries are expected in the catalog).
Check the modification timestamp on the catalog file (resolved via
$DISPATCH_CATALOG_PATH). If more than 14 days stale, flag it — the
catalog should be regenerated whenever triggers.yml files change.
python -c "
import os, datetime as dt
path = os.environ.get('DISPATCH_CATALOG_PATH') or os.path.expanduser('~/.claude/dispatch-catalog.json')
if os.path.exists(path):
mtime = dt.datetime.fromtimestamp(os.path.getmtime(path), dt.timezone.utc)
age = (dt.datetime.now(dt.timezone.utc) - mtime).days
print(f' {os.path.basename(path)}: {age}d old (mtime {mtime.isoformat()})')
else:
print(f' catalog absent at {path}')
"
The final response should look like this (markdown):
<`claude-wayfinder health --report` output verbatim, including the H1 "# Router Health Report">
## Analysis
<bullet list of FAIL'ing or warning-zone metrics with drill-downs>
### Recent drift events
<5-row list, or "none in the last week">
## Extended Notable Findings
### Top dispatched agents (last 30 days)
<table or bullets>
### Top invoked skills (last 30 days)
<table or bullets>
### `self_handle_unaided` rate (catalog coverage)
<count + caveat>
### Catalog entry counts
<skills/agents/routable counts>
### Catalog freshness
<one age line>
If --brief: omit the verbatim report (Step 2) — start the response with
## Analysis.
src/claude_wayfinder/_health.py and changing them is a separate
decision.dispatch-log.jsonl or router-drift.jsonl
do not exist, the corresponding hooks are not firing. Flag this as a
dispatch-pipeline drift event in its own right and recommend checking
the PreToolUse / Stop hooks in the consumer's hook registry./refresh-catalog or
claude-wayfinder catalog build.python not on PATH: the user has not run /setup-wayfinder yet,
or the plugin venv is not activated. Recommend /setup-wayfinder and
re-running this skill in a fresh session.npx claudepluginhub glitchwerks/claude-wayfinder --plugin claude-wayfinderProvides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.