Router Health

Router Health Skill

You are reporting on the health of the deterministic-dispatch router. This is a read-only skill — never mutate state, logs, or the catalog.

What this skill does

1. Runs python -m claude_wayfinder health --report.
2. Prints the report verbatim.
3. Adds an Analysis section with drill-down on any FAIL'ing or

near-threshold metric.

1. Adds an extended Notable Findings section with qualitative

observations from 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.

Path resolution

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.

Step 1: Run the report

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.

Step 2: Print the report verbatim

Unless --brief was passed, emit the captured markdown unchanged. Begin your response with the report.

Step 3: Analyze 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.

How to compute "warning zone"

| 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 |

Analysis

Recent drift events

Extended Notable Findings

Top dispatched agents (last 30 days)

Top invoked skills (last 30 days)

self_handle_unaided rate (catalog coverage)

Catalog entry counts

Catalog freshness

If `--brief`: omit the verbatim report (Step 2) — start the response with
`## Analysis`.

## Tone and discipline

- Be specific and quantitative. Cite exact counts, percentages, session-id
  prefixes, dates.
- Do not invent metrics that the script does not produce. Stick to the
  observed data.
- Do not recommend changes to thresholds — those are codified in
  `src/claude_wayfinder/_health.py` and changing them is a separate
  decision.
- Where a finding suggests action (regenerate catalog, investigate a
  bypass-heavy session), name the next step concretely with the command
  to run.
- If a log file is missing or empty, say so — never silently fall through
  with zero counts that look like "everything is healthy."

## Failure modes

- **Script exits non-zero**: surface stderr verbatim, recommend the user
  run the command directly to see the failure. Do not produce Analysis or
  Notable Findings sections — the source data is unreliable.
- **Log files missing**: if `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.
- **Catalog file missing**: report this as a catalog-availability outage
  and recommend running `/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.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [glitchwerks](https://github.com/glitchwerks)
- **Source:** [glitchwerks/claude-wayfinder](https://github.com/glitchwerks/claude-wayfinder)
- **License:** MIT
- **Homepage:** https://pypi.org/project/claude-wayfinder/

Install and usage instructions live in the source repository linked above.