Prompt Coach

---
name: prompt-coach
description: A hook-driven coach that reads every prompt sent to Claude Code and rewrites it toward proven prompting habits — definition-of-done, scoped references, guardrails, verification. Rules graduate as they are demonstrated, so the coaching fades as the user improves. The hook runs on its own, but load this skill when the user says "coach pause 10", "coach off <rule-id>", "coach on <rule-id>", "coach reactivate no-definition-of-done here", "disable praise", "coach ack every 10", "coach that was wrong", "coach false positive", "coach missed this", "bad nudge", or "analyze my last 20 prompts" — and whenever they ask why a nudge fired, what a rule means, how mastery is earned, or how to configure, pause, silence, or tune the coach.
---

# prompt-coach

## Quick start

### 60-second setup

```
/plugin marketplace add alexmond/alexmskills
/plugin install prompt-coach@alexmskills
/reload-plugins
```

Restart the session so the `UserPromptSubmit` hook registers. Then just prompt Claude normally — the coach analyzes every prompt in the background and nudges when a rule matches.

### What you'll see when a rule fires

As of v0.34 the coach is a **collaborator** (not a nagger): when a rule fires, Claude reads your prompt in context and rewrites it with the fix baked in, at the top of its response:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
💬 prompt-coach — I read your prompt as:

    "in src/auth/login.js, update handleLogin() to reject empty
     password submissions with a 422 and a 'password required'
     message. Keep the existing test suite green."

Changes:
  [1] Named the file + function (was: 'the login flow')
  [2] Made the behavior explicit + added a guardrail

Sources: https://…/be-clear-and-direct

Proceeding with this rewrite now — reply "no" to redo from your original, or "edit" to adjust.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
▸ Working from the rewrite.
<Claude answers your question from here, using that prompt.>
```

On a **clean** prompt you instead get a one-line `✓` heartbeat (v0.35). The coach is a suggestion, not a block — Claude answers your prompt normally. By default (v0.43) it **proceeds honestly**: the block says it's proceeding (not "reply yes to proceed") and Claude opens with a **`▸ Working from the rewrite / your original`** line so you always see which prompt drove the answer; silence = accept, and a `no`/`edit` next turn corrects. Prefer a real pause? Set `collaborator_gate: true` and Claude stops after the block and waits for your yes/no/edit (one extra round-trip per fired prompt). Rules graduate to "mastered" once you've **demonstrated** the good technique `min_demonstrations` times (default 3, v0.40 earned-mastery model), then the next dormant rule activates.

### The slash commands

| Command | When to use |
|---|---|
| `/prompt-coach:stats` | *"How am I doing?"* Health dashboard: prompts analyzed, emit rate, top-fired rules, mastery status. |
| `/prompt-coach:mastery` | *"Which rules mastered, which need reset?"* Per-rule breakdown + analysis (well-tested / barely-tested / untested masteries; close-to-mastery). |
| `/prompt-coach:config` | *"Change my settings."* Verbs: `show`, `get`, `set`, `describe`, `options`, `mastery`, `acceptance`, `sources`, `paths`, `analyze`, `library`, `dashboard`, `diff`, `export`, `reset`. |
| `/prompt-coach:library` | *"Show me a prompt for X."* Matches your task to the closest gold-standard template from Anthropic's Claude Code Prompt Library (v0.47). |
| `/prompt-coach:dashboard` | *"Show me a UI."* Local web dashboard (v0.44) — six tabs: Stats, Mastery (by tier, with reference URLs), live Config editor, Options, Library, and the ranked Sources tab (v0.48). Light/dark toggle. |
| `/prompt-coach:help` | *"What are my options?"* Compact live-config card + command list + say-it cheatsheet. |
| `/prompt-coach:report-issue` | *"The coach was wrong."* Files a redacted GitHub issue (first-5-words + structural signature only). |

#### Web dashboard (v0.44)

`/prompt-coach:dashboard` launches a **zero-dependency (Python stdlib only) local server** on
`127.0.0.1` (`scripts/serve.py`). It renders the coach's **stats**, **mastery** grouped by tier
(status badge · `demos/min` · fires · clickable **reference URLs** · per-rule reset), and a **live
config editor** — every schema key with its description and a type-aware control (checkbox / number /
select / text) that **saves to global or repo scope** on change. Writes reuse `config.py`'s
`build_dashboard` / `api_set` / `api_action`, so validation and scope rules are identical to the CLI.
Two more tabs: **Library** (browse the Prompt-Library templates) and **Sources** (v0.48 — every
citation deduped and ranked by importance). A toolbar **light/dark toggle** (🌙/☀️) persists your
choice on top of the OS default. Local-only, no auth by design. Raw JSON without the server:
`config.py … dashboard`.

#### Prompt Library integration (v0.47)

The coach vendors an offline snapshot of [Anthropic's Claude Code Prompt Library](https://code.claude.com/docs/en/prompt-library)
— 52 gold-standard, tagged, slot-templated prompts — and matches your task to the closest one with a
zero-dependency keyword/tag matcher (`scripts/library.py`, no network/embeddings). Two touchpoints:

- **On-demand** — `/prompt-coach:library "<task>"` or *"show me a prompt for X"* returns the
  closest template(s), offered adapted to your file paths. Browse all on the dashboard's **Library** tab.
- **Rewrite grounding** — when a rule fires and `library_hints` is on (default), the collaborator
  rewrite is anchored to the closest template's phrasing + slots (only when a confident match exists).

Refresh the snapshot with `make library-refresh` (fetches the live docs). The prompts are Anthropic
documentation content, vendored with attribution.

### Say-it phrases (natural language)

Claude edits your config file when you say any of these:

**On/off** (v0.29+):
- *"disable prompt-coach"* / *"turn coach off"* — full silence in this scope (`enabled: false`)
- *"enable prompt-coach"* — turn it back on
- *"coach pause 10"* — temporary silence for 10 prompts

(Rendering is always inline. As of v0.38 the coach is collaborator-only — Claude
rewrites your prompt fresh each time — so the pre-v0.38 `nudge_style`,
`voice_preset`/`voice_source`, and anti-habituation options were all removed.)

**Analyze / docs / files** (v0.36+):
- *"analyze this prompt: <text>"* / *"analyze my last 20 prompts"* — full-catalog coaching on demand
- *"open the docs for <rule>"* — open the Anthropic guide section in a browser
- *"show me the skill folders"* — list the plugin's folders, state files, runnable scripts

**Pause / disable:**
- *"coach pause 10"* — silence nudges for the next 10 prompts
- *"coach off <rule-id>"* — permanently disable one rule
- *"coach on <rule-id>"* — re-enable it

**Bug reporting:**
- *"coach that was wrong"* — flag the PRIOR prompt for `/report-issue`

### First-day tweaks

To fully disable the coach in this repo/scope:
```
"disable prompt-coach"
```
(Coach is collaborator-only + inline as of v0.38 — no rendering mode or voice to pick.)

If you're being nudged too often:
```
"show me prompt-coach mastery"        (dashboard of practicing vs mastered rules)
"coach off <rule-that-keeps-firing>"  (permanent silence per rule)
"coach pause 10"                      (silence everything for 10 prompts)
```

### Companion skill: log-review

For cross-repo analytics of coach activity, say **"log review"** or **"daily review"**. That invokes the standalone `log-review` skill at `~/.claude/skills/log-review/` (redacted-by-default output, safe to paste anywhere).

---

## How it works

A `UserPromptSubmit` hook analyzes every prompt you send Claude Code, matches it against a
catalog of prompting-best-practice rules, and — in **collaborator mode** (v0.34+) — asks Claude
to rewrite your prompt inline in the same response, addressing whichever candidate rules actually
apply. Rules graduate to "mastered" once you've *demonstrated* the good technique
`min_demonstrations` times (default 3) with no recent relapse (see Earned mastery), at which point
the next dormant rule activates. The coach fades as your prompts improve.

## What it watches for

**Six tiers, 42 rules total** — unevenly sized (L1 6, L2 4, L3 11, L4 5, L5 11, L6 5). Only 6
rules are active at once (`max_active_rules`, default 6) — lower tiers dominate; as an L1 rule
masters, an L2 rule activates in its place, and so on.

**L1 — fundamentals**
| Rule | Catches |
|---|---|
| vague-reference | "Fix it" / "improve this" with no named file/function |
| no-definition-of-done | Action verb with no acceptance criteria |
| unbounded-scope | "all / every / entire X" attached to a mutating verb |
| improve-without-metric | "better / faster / cleaner" with no measurable target |
| missing-guardrails | Heavy verb (refactor/rewrite/migrate) with no "don't touch X" |
| no-answer-shape | "What are X" / "how much of Y" question without a format spec (elevated L2→L1 in v0.12) |

**L2 — intermediate**
| Rule | Catches |
|---|---|
| compound-tasks | Three+ action verbs joined by "and" |
| no-verify-loop | Implementation ask with no verification step |
| missing-context-fetch | "The failing test / the issue" with no identifier |
| no-format-spec | Ask for summary/list/report with no shape |

**L3 — classical prompting techniques**
| Rule | Catches |
|---|---|
| no-adversarial-check | High-stakes ask (security/migration/prod/delete) with no skeptic |
| retry-without-diagnosis | Short "try again" with no new information |
| no-few-shot | "Like X" / "in the style of Y" without an example |
| no-chain-of-thought | Reasoning ask (why/debug/trace) without "think first" |
| no-rubric | Judgment ask ("is this good?") without criteria/axes |
| no-uncertainty-budget | Investigative ask with no "if unsure, say so" |
| untrusted-content-execution *(v0.46+)* | Paste external content (email/page/issue) + "do what it asks" — prompt-injection vector |

**L4 — goals & loops**
| Rule | Catches |
|---|---|
| implicit-goal | Action prompt with no "so that / in order to / why" clause |
| unbounded-iteration | "Keep improving" without a stopping condition |
| no-rubric-for-refine | "Refine this" without naming which axis to improve |
| speculative-generality *(v0.46+)* | "Make it generic / pluggable / so we can add more later" — building for a hypothetical future (YAGNI) |

**L5 — Claude-Code tool-native**
| Rule | Catches |
|---|---|
| no-plan-mode-for-risky | Migration / delete / rewrite ask with no "plan first" |
| no-task-list-for-multi-step | 3+ action verbs without a TaskCreate / checklist ask |
| no-agents-for-parallel-lookup | Multiple independent lookups without parallel agents |
| no-role-for-critique | "Review my X" without invoking a role (skeptic / security / reviewer) |
| no-panel-for-contested-design | "Which is better / torn between" without brainstorm-panel |
| no-workflow-for-fanout | "For each of these 20+ things" without Workflow / parallel agents |
| incremental-routing | Multi-step task routed one terse step at a time ("continue" / "one after another" / "do the next one") instead of a batched task list / Workflow |
| workflow-fanout-no-verify | Orchestrated fan-out (workflow / parallel agents / sweep) to *discover* many items with no adversarial verify + dedup pass — scale without reliability |
| no-scheduler-for-recurring | A recurring clock/calendar task ("every morning" / "nightly" / "at 9am") phrased as a one-off — belongs in `/loop --interval <cron>` or `/schedule` |
| no-loop-for-polling | "Poll / retry / monitor until <state>" with no bounded loop — a self-paced `/loop` with the observed state as its stopping condition |
| no-goal-for-outcome | A target end-state ("get the build green" / "make all tests pass") with no `/goal <condition>` handoff to iterate + self-evaluate |

**L6 — skill-awareness**
| Rule | Catches |
|---|---|
| no-skill-lookup | "How do I X" / "what's the standard way" without checking existing skills |
| pattern-worth-abstracting | "Again / same as before / yet another" — rule of three, worth a skill? |
| no-skill-composition | Multi-step repeatable ceremony not named as a skill candidate |
| premature-abstraction *(v0.46+)* | "These two are the same — extract a shared base" at N=2 — the wrong-abstraction trap (rule of three) |

## Encouragement layer (v0.3+)

The coach also *praises the specific positive behaviors* mirroring the negative rules — 42 detectors (one per rule),
sparing (default 1-in-10 clean prompts + always on mastery + always on first-after-fire), and
grounded in behavioral-science literature (Brophy 1981, Mueller & Dweck 1998, Fogg 2019, Deci & Ryan
2000, Kohn 1993). Design choices:

- **Never on a nudged prompt** — praise + correction on the same prompt dilutes both (Kohn).
- **Specific, not generic** — describes what you did (`"you attached a metric to 'better'"`) rather
  than evaluating you (`"great prompt"`).
- **Process, not trait** (Dweck) — praises the *technique*, not you.
- **Variable-ratio** (Skinner) — intermittent praise stays potent; every-time praise becomes noise.
- **Rotated phrasings** — 2–3 per rule, plus a light touch of warmth/humor.
- **Milestone events** — a rule graduating to *mastered* and a "first-after-fire" (you did the
  thing you were nudged on last prompt) are always recognized regardless of ratio.

> **v0.35 fix:** the praise layer had no inline-render branch, so from v0.29 (when rendering
> became inline-only) through v0.34 all of the above — including the mastery congrats — was
> computed then silently dropped. v0.35 restores it: mastery renders `🎓 prompt-coach — you
> mastered …`, first-after-fire and positives render `✨ prompt-coach — …`.

## Liveness acknowledgment (v0.35+)

The coach used to speak *only* on a rule hit, so a clean prompt produced silence and you
couldn't tell it was alive. `ack_clean` (default **on**) fixes that: on a clean prompt where
nothing else fired, it emits one compact ambient line —

```
✓ prompt-coach · clean prompt · closest to mastery: no-verify-loop 2/3 demonstrated
```

**This is not praise — it's a heartbeat.** The distinction is deliberate and grounded:

- **Informational, not evaluative.** Praise conveys a judgment ("good job") and must stay
  sparing or it wears out (Kohn 1993; Deci & Ryan 2000 on controlling vs *informational*
  feedback). A progress counter conveys competence *information* — like a test runner's green
  dot or a shell's git-branch segment — so it can be frequent without the wear-out.
- **Endowed-progress effect** (Nunes & Drèze 2006) — surfacing "N/threshold to mastery" makes
  the goal feel closer and pulls you toward it.
- **Status channel, not alert channel** (Sasse & Rashid 2013 on alert fatigue) — a distinct
  `✓` glyph (vs 🎯 nudge / 🔄 refresher / 💡 tip / ✨🎓 praise) reads as ambient status, not a
  demand for action.

**Priority ladder:** nudge/collaborator › refresher › praise › tip › ack. The ack fires only
when nothing else spoke, so the coach never stacks two messages on one prompt.

**Config:** `ack_clean` (bool, default true) · `ack_ratio` (int, default 1 = every clean prompt;
raise to 5/10 for a quieter pulse). Say *"turn off prompt-coach acks"* or *"coach ack every 10"*.

## Conversational short-circuit (v0.6+)

Many prompts in an ongoing conversation aren't full asks — they're **approvals**
(`sure`, `publish`, `go`, `ship it`), **multi-choice picks** (`1 and 2`, `a and b`,
`option a`), or **continuations** (`continue`, `next`, `thanks`). The coach's rules
would misfire on these, and the typo normalizer would over-correct short conversational
words (e.g. `publish` → `polish` at edit distance 2).

`is_conversational()` catches these and short-circuits the analysis: no rule matching,
no typo correction, no praise, no streak updates. The prompt is still logged (with
`outcome: skipped:conversational`) so you can audit what was skipped. If a rule ever
needs to fire on this class of prompt, log inspection tells you to widen the trigger.

## Typo tolerance (v0.5+)

A pre-pass normalizes each prompt against a curated set of ~90 trigger words drawn from the rule
catalog — dyslexic-friendly, transposition-friendly, deterministic, and zero-dependency (banded
Levenshtein, ~1 ms). Corrections are made only when:

- The token is ≥ 5 chars, all-alphabetic, and NOT already a trigger word.
- Its closest trigger word is **uniquely** the closest (ties = no correction, so `text` doesn't
  become `test`).
- Adaptive tolerance: distance-1 for tokens ≤ 6 chars, distance-2 for longer (kills the
  "public ↔ rubric" class of collision, keeps "refacotr ↔ refactor").

Examples that get corrected: `refacotr` → `refactor`, `evrything` → `everything`,
`veryfy` → `verify`, `cleanre` → `cleaner`, `migrat` → `migrate`. Every correction is logged.

**Fallback count is a self-report signal.** Rising `normalization_stats.tokens_corrected_total` /
`prompts_with_corrections` (in `~/.claude/prompt-coach/state.json`) says the rule regexes aren't
covering your real prompts and it's worth tuning. Once the LLM fallback (v0.6, opt-in) ships,
`llm_fallback_stats.calls_total` gives the same signal one level up. Ask *"show me prompt-coach
stats"* and Claude will summarize.

Set `typo_tolerance: 0` in config to disable the normalization pass entirely.

## Configuration

Config resolves in order: repo local → user global → default. Run
`/prompt-coach:config show` for the live, schema-backed list. Key knobs:

- `enabled` — master switch; `false` = the hook returns immediately (default: true)
- `ack_clean` / `ack_ratio` — the `✓` liveness heartbeat on clean prompts + its rate (default: true / 1)
- `show_source_urls` — full clickable doc URLs in the coach block (default: true)
- `collaborator_gate` — make the block a real confirmation gate (default: false = honest proceed + `▸ Working from` marker; true = stop & wait for yes/no/edit)
- `min_demonstrations` — **earned mastery (v0.40)**: times the mirroring positive must fire (you *used* the technique) before a rule can master (default: 3)
- `regression_guard` — clean prompts since the last fire required alongside the demonstrations (default: 3)
- `inactive_after` — clean_streak with zero demonstrations after which a rule retires *inactive* (default: 15)
- `graduation_threshold` — clean-streak recency/decay signal; no longer drives mastery since v0.40 (default: 15)
- `min_fires_for_mastery` — legacy v0.27 gate, superseded by `min_demonstrations`; retained but ignored
- `cooldown_prompts` — min prompts between same-rule fires (default: 5)
- `mastered_cooldown_prompts` — cooldown between refresher fires on mastered rules (default: 50; `0` disables)
- `max_active_rules` — cap on practicing rules active at once (default: 6)
- `pause_until_prompt` — skip until global `prompt_count` passes this
- `disabled_rules` — array of rule ids to permanently silence
- `praise_ratio` / `praise_on_mastery` / `praise_on_first_after_fire` / `disable_praise` — encouragement layer
- `tips_enabled` — proactive advanced-technique tips (default: true)
- `typo_tolerance` — Levenshtein edit distance for typo normalization (default: 2, `0` disables)

> **v0.38 removed** the legacy `nudge_style`, `voice_preset`/`voice_source`, and the
> anti-habituation keys (`saturation_threshold`, `silence_window`, `silence_duration`,
> `disclosure_medium_at`, `disclosure_short_at`) along with the hand-written nudge path.
> The coach is **collaborator-only**: when a rule fires Claude rewrites your prompt fresh,
> so there is no preset to pick and no repeated text to habituate to.

Full source citations behind each rule: [`docs/sources.md`](../../docs/sources.md).

## Cross-repo daily review — moved out (v0.23+)

The v0.21-v0.22 `/prompt-coach:daily-review` command was extracted
to a standalone user skill at `~/.claude/skills/log-review/`. Rationale:
its output (repo names, per-repo activity) shouldn't be produced by the
coach; keeping it separate means the coach never generates content that
could leak repo topology when pasted into a GitHub artifact.

Invoke by saying *"log review"* / *"daily review"* / *"what's new"* — Claude
picks up the skill from `~/.claude/skills/log-review/`. Redacted-by-default
(`repo-1`, `repo-2`, …); `--show-repos` for local inspection. Watermark for
"since last review" semantics. Data source is unchanged: it reads the same
`.claude/prompt-coach/log.md` files the coach writes.

## Options + interactive flows + mastery (v0.19+)

Three additions on top of v0.18's `:config`:

- `+/prompt-coach:config options <key>+` — enumerates legal values for a key
  with per-choice explanations. For int/bool/list, shows current + default +
  example + description. Answers *"what modes exist?"* without needing to already know.
- `+/prompt-coach:config quick+` — interactive multi-choice picker for the
  ~4 high-value settings (`ack_clean`, `show_source_urls`, `praise_ratio`, `tips_enabled`).
  Claude walks you through with AskUserQuestion; each answer routes to `:config set`.
- `+/prompt-coach:config full+` — same pattern for every schema key. Enum
  keys → picker; numeric/bool → "keep current / type new value / reset to
  default". Longer flow; you can skip categories.
- `+/prompt-coach:config mastery+` — dashboard of rule states: *mastered*
  (with mastery date), *in-progress* (fires_total > 0, streak/threshold),
  *dormant* count by tier. Answers *"how am I doing?"*.
- `+/prompt-coach:config mastery-reset <rule-id>+` — resets one rule's
  fires/streak/status/mastered_at (dry-run first).
- `+/prompt-coach:config mastery-reset-all+` — wipes all rule state
  (preserves `prompt_count` and non-rule state; dry-run first).

Under the hood, enum keys now carry `choice_descriptions` in `CONFIG_SCHEMA` —
same forward-compat pattern as v0.18. Adding a new enum config means adding a
`choice_descriptions` dict; `options` picks it up automatically.

## Config surface (v0.18+)

The coach's config spans ~34 keys across six categories. `/prompt-coach:config`
is the structured surface — it reads a `CONFIG_SCHEMA` metadata dict alongside
`DEFAULT_CONFIG`, so future options are picked up automatically once they land in the
schema.

```
/prompt-coach:config                         categorized dashboard
/prompt-coach:config show <category>         one category only
/prompt-coach:config get <key>               resolved value
/prompt-coach:config describe <key>          type, default, choices, since
/prompt-coach:config options <key>           legal values + per-choice notes
/prompt-coach:config set <key> <value>       validate + write
/prompt-coach:config reset <key>             remove your override
/prompt-coach:config reset-all               wipe scoped config (confirm!)
/prompt-coach:config diff | export           changed keys | resolved JSON
/prompt-coach:config mastery | acceptance    mastery ledger | accept/reject rate
/prompt-coach:config sources [<rule>]        citation trail + doc URLs
/prompt-coach:config paths                   skill folders, state, scripts
/prompt-coach:config analyze "<text>"        full-catalog read of a prompt
/prompt-coach:config library ["<task>"]      match / list Prompt-Library templates
/prompt-coach:config dashboard               the consolidated dashboard JSON
```

Flags: `--scope global|repo` (default `global`), `--dry-run` (on set/reset), `--json`
(machine-readable).

**Categories**: `output`, `rule-activation`, `mastery`, `praise`, `typo-tolerance`,
`llm-fallback`.

**Say-it phrases still work** — you can keep saying *"coach off no-few-shot"*,
*"disable praise"*, *"coach pause 10"*, etc. Claude routes those to `:config set` under the hood.
The command is the discoverable path when you don't know what the options are called.

Writes are deep-merged into the target JSON — keys the schema doesn't know about
(e.g. forward-compat entries from future versions) are preserved, not stripped.
Invalid values (wrong type, not in `choices`) are rejected with a clear error.

## Earned mastery (v0.40+)

Mastery is driven by **demonstrations — times you actively *used* the good technique** (the
mirroring positive detector fired), not by the absence of the mistake. Before v0.40 a rule
graduated after a clean streak, but "clean" just meant the anti-pattern was absent — and since
most prompts don't exercise most rules, a rule could master on prompts unrelated to it.

Every rule now has a positive mirror (42/42). When a positive fires it's a demonstration:
`demonstrations` **drives mastery**, `clean_streak` is demoted to a recency guard, `fires_total`
is a regression signal. A rule masters when `demonstrations ≥ min_demonstrations` (default 3)
and it hasn't relapsed in the last `regression_guard` prompts. A rule neither demonstrated nor
tripped over a long window retires *inactive*. Existing masteries are **grandfathered** (tagged
`mastery_basis: legacy`); `mastery-reset <rule>` makes one re-earn it honestly.

## Adaptive coaching (v0.41+)

The coach learns which rules are worth firing *for you* by closing the loop on every rewrite.

- **Acceptance loop (P1)** — the turn after a rewrite, your reply is recorded per rule:
  `yes`→`accepted`, `edit …`→`edited` (a *positive* signal — coaching landed), `no`→`rejected`.
  A fresh unrelated prompt records nothing (no guessing at implicit rejections). Yields a
  per-rule **acceptance rate** = `(accepted + edited) / outcomes`.
- **Precision-gated activation (P2)** — a rule below `precision_floor` (0.15) over
  `min_outcomes_for_gating` (4) outcomes is demoted `dormant` and stops firing; an **explore
  slot** re-admits one dormant rule every `explore_period` (10) prompts. A **fatigue cap**
  (`max_nudges_per_window`, default 6 per 20) silences excess rewrites (still logged).
- **Decaying mastery (P3)** — mastery isn't terminal. A mastered rule carries a review clock on
  an expanding schedule (`review_intervals_days` = `[30, 90, 180]` days of non-use); each natural
  use resets + advances it. If it lapses, the rule decays to a `watch` tier and must be freshly
  re-demonstrated to re-graduate. Grounded in skill-decay + spacing-effect research.

## Mastery ≠ silence (v0.9+)

Mastered rules aren't permanently dormant — they still evaluate every prompt, just emit rarely.
When only a mastered rule matches (no practicing rule fired), you get a **refresher**: a
one-line softer box (`🔄 prompt-coach — refresher on <rule>`) rather than the full nudge.

Cooldown for practicing rules: 5 prompts. **Cooldown for mastered rules: 50 prompts** (10×
longer). Set `mastered_cooldown_prompts: 0` in config to disable refresher firing entirely
(reverts to permanent-silence-on-mastery behavior).

**Priority when both fire in the same prompt**: nudge (practicing) > refresher (mastered) >
praise. Nothing dilutes anything.

**Optional self-healing** (`demote_on_regression: {enabled: false, threshold: 3, window: 30}`):
if a mastered rule fires 3+ times within 30 prompts, demote it back to practicing. Off by
default — being surprised by a graduated rule reactivating is unpleasant. Users who want strict
self-healing turn this on.

## On-demand analysis — `/prompt-coach:analyze` (v0.37+)

The passive hook is quiet by design — it only checks the few *active* rules. But the skill
carries the whole prompting-knowledge catalog, so you can point it at a prompt on demand and
get a **full-catalog read** (all 42 rules × 6 tiers + positive detectors), not just the active
subset.

Two modes:

- **A specific prompt** — *"analyze this prompt: refactor the whole auth module to be cleaner"*.
  You get every rule that fires (with its tier, the fix, and a clickable doc URL) plus a
  rewritten prompt that resolves the top issues.
- **Your recent history** — *"analyze my last 20 prompts"* / *"how have I been prompting?"*.
  Reads this repo's coach log, runs the full catalog on each, and reports your clean rate, the
  top recurring rules, and one habit to focus on next.

Backed by `config.py analyze "<text>"` / `analyze --last N` (add `--json` for raw data). The
slash command wraps it with a coached narrative. Read-only — never touches mastery or config.

```
$ …/config.py analyze "fix it and make it better and faster"
── prompt analysis ─────────────────────────────────────
  7 rule(s) fired (full catalog):
    · L1 vague-reference — Vague reference
    · L1 no-definition-of-done — No definition of done
    · L1 improve-without-metric — Improve without a metric
    · L2 no-verify-loop — No verify loop
    · L4 implicit-goal — Action without goal
    …
```

## Introspection — `/prompt-coach:stats`

Type `/prompt-coach:stats` (v0.8+) to see a compact dashboard: total prompts analyzed,
nudge/praise/skipped counts, emit rate, most-fired rules, mastered rules, top typo corrections,
and current config. Answers "is this thing actually doing anything?" without opening files.

Read-only; the command never modifies state.

## Reporting bad calls (v0.13+)

If the coach mistreated a prompt (false positive, false negative, wrong rule, bad wording),
mark it on the **very next turn** with any of these phrases:

- *"coach that was wrong"*
- *"coach missed this"*
- *"coach false positive"*
- *"bad nudge"* / *"wrong nudge"*
- *"coach mistreated my prompt"*

The analyzer flags the PRIOR substantive prompt's analysis (not the current complaint) into
`.claude/prompt-coach/candidates.jsonl`. Later, run:

```
/prompt-coach:report-issue
```

The command reads the queue, computes a structural signature (word count, verb-shape,
has-file-ref, is-question, etc.), redacts to the **first 5 words** of the prompt only, asks
you for a one-line annotation per case, shows a full preview, and only then files a
`gh issue create` to `alexmond/alexmskills` with label `prompt-coach` — after you confirm.

**Privacy guarantees**: only first-5-words + structural booleans + your annotation get filed.
Full prompts stay in `log.md` locally. You see the exact payload before it's posted.

## Pause / disable (say-it phrases)

- *"Coach pause 10"* — silence nudges for the next 10 prompts. Claude sets `pause_until_prompt` in
  global state.
- *"Coach off vague-reference"* — permanently disable a single rule. Claude appends the id to
  `disabled_rules` in `~/.claude/prompt-coach/config.json`.
- *"Coach on vague-reference"* — remove from `disabled_rules`.
- *"Coach reactivate no-definition-of-done here"* — re-open a rule that graduated globally, just
  for this repo. Claude adds the id to `reactivated` in `.claude/prompt-coach/state.json`.

## State layout

```
~/.claude/prompt-coach/
├── config.json        # global config (enabled, thresholds, disabled_rules)
└── state.json         # global mastery ledger: fires_total, clean_streak, status per rule

<repo>/.claude/prompt-coach/
├── config.json        # per-repo overrides (enabled, disabled_rules)
├── state.json         # per-repo fires_here, reactivations
└── log.md             # rolling log of nudges + prompt previews
```

## Verify it's on

- A rule-firing prompt should produce the inline `💬 prompt-coach` block at the start of
  Claude's response; a clean prompt produces the one-line `✓` heartbeat. Either way
  `.claude/prompt-coach/log.md` keeps growing.
- Global counter: `jq '.prompt_count' ~/.claude/prompt-coach/state.json` should increment per
  prompt.
- If neither happens, the hook may not be registered — check `enabledPlugins` in
  `.claude/settings.json` for `prompt-coach@alexmskills`.

## Future — Java MCP server

The current Python + `UserPromptSubmit` hook is CLI-only. A Java MCP
server is planned so the coach can run in claude.ai chat, aggregate
telemetry across users, and support persistent per-user state. Living
spec: [`docs/java-mcp-spec.md`](../../docs/java-mcp-spec.md) — updated
on every minor version bump. It captures the target architecture, MCP
surface, canonical rule catalog format, data model, privacy model, and
migration path from the current Python plugin.

The prerequisite for building the server is **training data from real
users at scale**, not a single maintainer's log. The
`/prompt-coach:report-issue` command already produces
training-data-shaped payloads (structural signature + first-5-words +
user annotation) — that's the collection mechanism the future server
will consume.

## Design notes

- **Pure heuristics.** Rules are regex + short-window checks; no LLM call per prompt. Cheap,
  deterministic, ~10 ms.
- **False positives are OK.** Cooldowns prevent pestering; graduation rewards you for consistent
  clean prompts even in the face of an over-eager rule.
- **Sources are diverse.** Each rule cites 2–3 outside-of-Anthropic and inside-Anthropic sources
  so the catalog isn't opinion-of-one.
- **Graduated to 1.0.0** (2026-07-28). It cleared its own bar — nightly use across dozens of
  repos with rules mastered per repo — and dropped the `-beta` suffix. Development continues on
  the stable line; see the roadmap for the eval harness (measured per-rule precision) and the
  planned Java MCP server.