hotpath-miner

name	hotpath-miner
description	Find the user's Claude Code hotpaths — recurring procedures they and the agent keep re-deriving from scratch — and compile the converged ones into deterministic zymi pipelines. Use when the user asks to "find my hotpaths", "mine my sessions", "what do I keep doing over and over", "что я делаю по кругу", asks for a hotpath report, or wants to turn a recurring workflow into a reusable pipeline ("promote X", "compile this"). Detection is a local, deterministic miner over ~/.claude/projects — no LLM call, no API key, nothing leaves the machine.
metadata	{"version":"0.2-alpha"}

hotpath-miner

You drive a two-phase loop: mine (deterministic — a zymi pipeline counts what recurs in the user's own session transcripts) and promote (judgment — you distil a converged procedure into a pipeline, using the bundled rubric).

SKILL_DIR below means the directory this SKILL.md lives in. Run everything from there: the miner writes its output to SKILL_DIR/data/ (gitignored, private — the report quotes the user's own prompts; never paste it anywhere public).

1. Preflight — the engine

The miner runs on zymi (>= 0.9):

zymi --version

If missing, install it (tell the user what you're doing and why — many users of this skill are not developers):

uv tool install zymi-core     # preferred; puts `zymi` on PATH
# no uv? → pip install zymi-core   (or install uv first)

No API key is needed — the miner has no LLM step.

2. Mine — the user pressed one button, you do the rest

The user said "find my hotpaths" and is done; everything below is yours. Assume they are NOT a developer: no JSON, no env vars, no jargon in what you show them — thresholds and file paths are for you, not for them.

Pass 1 — deterministic (never asks anything):

cd SKILL_DIR && zymi run hotpath_miner

Then read data/report.md and explain it in the user's language, briefly:

• 🟢 Compilable — recurring work with a stable command sequence. These are worth freezing into a pipeline. Call out 🆕 (new since last run) and ↑ (heating up).
• 🔴 Judgment — frequent asks with no stable sequence (research, writing). Correctly left to a live model; do NOT offer to compile these.
• ⚪ Suppressed — already promoted, hidden from the green list.

Recommend at most 1–2 candidates actually worth promoting (breadth across projects beats raw session count). Don't oversell fragments like git status -> git add — a good candidate is a procedure, not a tic.

Tuning, if the user's history is small or the report is noisy:

• HPM_MIN_SESSIONS=3 zymi run hotpath_miner — stricter rule-of-three (default 2; raise for busy histories, keep 2 for small ones).
• HPM_JACCARD_SEQ (default 0.5) / HPM_JACCARD_DEEP (default 0.4) — clustering greed for verb-sets / deep infra tags; raise if unrelated work is fusing into one candidate, lower if one hotpath splits into several.
• The prompt-theme buckets are substring lexicons: generic defaults live in scripts/intent_lexicon.py; a personal {label: [substrings]} dict in data/intents.json replaces them.

Pass 2 — assisted (you are the brains; the user just confirms)

The miner leaves exactly two judgment calls open, and you answer both. After pass 1, check:

1. Lexicon blind spots — the report's 🕳 footer counts sessions no theme bucket matched. If that's a big share (or the intent section looks empty / wrong), read data/lexicon_gaps.md: recurring words from the uncovered sessions. Draft new buckets from the user's own vocabulary — substrings lowercased, ≥ 3 chars, words they actually type, not descriptions.
2. Red-list review — read data/judgment_digest.md: per red candidate, how close its best command sequence came to the 60% bar and which commands its sessions share. Vouch for a candidate ONLY if the evidence shows one repeatable procedure (e.g. the same command in nearly every session); when in doubt, don't — red is the safe verdict. Never vouch for a bucket you are only now creating in answer 1: its evidence sheet doesn't exist yet, so you'd be vouching blind. If it's real, it shows up on the next run's red list with evidence — vouch then.

If either answer is non-empty, confirm with the user in ONE short, plain-language message, e.g.: "I see you often ask about Spark jobs — I'll start tracking that theme. And it looks like those runs are really one repeatable procedure; treat it as automatable?" Never show them JSON or ask them to pick thresholds. Then run the assisted pass, answering both questions yourself — one line per question, none where you have nothing:

printf '%s\n%s\n' '{"spark-job": ["spark", "airflow"]}' 'deploy-docs' \
  | zymi run hotpath_miner_assisted

• line 1 → new lexicon buckets, JSON {label: [substrings]} (or none); merged into data/intents.json.
• line 2 → red candidates to vouch for, comma-separated names from pass 1's judgment digest (or none); saved to data/overrides.json and lifted into the green list, marked ⚠️ caller-vouched, on this and every future run.

Both answers stick, so pass 2 is only needed again when new blind spots or questionable reds appear. If both answers would be none, skip pass 2 entirely — pass 1's report is already the final answer. To retract a vouch that turned out wrong, remove its name from data/overrides.json and re-run. (A human running this by hand can instead just run zymi run hotpath_miner_assisted and answer the two questions at the terminal in plain text; none is always safe, and a single-token label: word, word line works in place of JSON.)

Present the final report per the guidance above. A ⚠️ caller-vouched green is still a candidate, not a certainty — say so if you recommend one.

If ~/.claude/projects is empty or missing, say so — there is nothing to mine until the user has some Claude Code history.

3. Promote — when the user picks a candidate

Read skills/promote-hotpath/SKILL.md (bundled, relative to SKILL_DIR) and follow it exactly. In short: python3 scripts/dossier.py <candidate> for the grounding, distil the converged procedure (anchor on outcome, drop dead-ends, keep load-bearing fallbacks), draft a safe parameterised pipeline (secrets → .env, mutating steps approval-gated, loud verify), validate it loads — and the user runs the first real invocation, never you.

A promoted pipeline can then be exposed as an MCP tool (expose.mcp in the pipeline + claude mcp add), so future sessions call the procedure instead of re-deriving it. After a successful promote, append the candidate's key to data/promoted.json so the miner suppresses it.

Guardrails

• Never run a freshly compiled pipeline against the user's live systems — build + validate-load only; the first invocation is theirs.
• Never put a secret in YAML or in the report; secrets go to a gitignored .env.
• The report AND the digests quote the user's own prompts — private data. Quote single lines to discuss; never export them, paste them into anything public, or send them to any external service.
• If the user asks whether this leaks their history anywhere: no — the miner is local, offline and telemetry-free, and the README's Privacy section shows how to verify that claim rather than trust it. Walk them through it.