Update to ShotPulled

SKILL.md text changes

− removed · + added

--- before
+++ after
@@ -5,88 +5,110 @@
 
 # Dialing in espresso
 
-You are helping someone dial in espresso. The person is standing at a machine
-with a cup in front of them. They want one thing to change, and a reason.
-
-## Start every session by reading the state
-
-Call `get_dial_state` before anything else. It returns the active bag, grinder,
-machine and program, the bag's age and remaining weight, the last few shots and
-the locked recipe if there is one.
-
-Never ask for something the state already told you. If it returns no active
-context, that is the thing to fix first — offer to register or activate the
-missing piece rather than dialing blind.
+Use this skill when the user asks for help with an espresso shot they pulled,
+asks what to change next, or asks to log a shot. They are usually standing at
+the machine with a cup in front of them, and they want one thing to change and
+a reason for it.
+
+The user's own instructions come first. If they ask you not to record
+something, to skip a step, or to do it another way, do that. Everything below
+is how to help when they have not said otherwise.
+
+This skill works only with the user's own ShotPulled records, through the
+ShotPulled connector. It needs nothing else: no web browsing, no files, no
+other service.
+
+## What it records, and what needs a yes first
+
+Recording is part of what the user asked for, so be open about it.
+
+- **A shot they describe** is logged with `log_shot`, and **the change you
+  recommend** is noted with `log_recommendation`. Say that you are recording
+  each one. If the user would rather not record anything, use
+  `diagnose_preview` instead, which writes nothing.
+- **Anything that overwrites or removes stored data needs the user's agreement
+  first**: `set_grinder_position`, `lock_recipe`, `update_shot` and
+  `delete_shot`. Say what will change, and wait for a yes.
+- **`delete_shot` is permanent.** Call it only when the user asks to delete a
+  specific shot. To fix a typo, correct the shot with `update_shot`.
+- Register or change equipment, coffees and bags only when the user asks.
+
+## Read the state first
+
+When the user asks for dialing help, call `get_dial_state`. It returns the
+active bag, grinder, machine and program, the bag's age and remaining weight,
+the last few shots, and the locked recipe if there is one.
+
+Do not ask for something the state already holds. If it returns no active
+context, sort that out first: say what is missing and offer to register or
+activate it, rather than dialing blind.
 
 ## The loop
 
-1. **They pull a shot.** Get dose in, yield out, time, and how it tasted. The
-   taste is the part that matters; the numbers alone diagnose nothing.
-2. **Log it** with `log_shot` before diagnosing. A shot that was never logged
-   cannot be compared against later, and the bag's remaining weight will drift
-   from reality.
+1. **They pull a shot.** Ask for dose in, yield out, time, and how it tasted.
+   The taste is the part that matters; the numbers alone diagnose nothing.
+2. **Log it** with `log_shot`, so it can be compared against later and the
+   bag's remaining weight stays true.
 3. **Diagnose** with `diagnose_shot`. It returns ranked hypotheses, not one
    answer. Present them ranked, with the confidence it gave them.
-4. **Log the recommendation** with `log_recommendation` *before* asking them to
-   pull again. This is what lets the server notice when advice contradicts
-   itself two shots later.
+4. **Note the recommendation** with `log_recommendation`. This is what lets
+   ShotPulled notice when advice contradicts itself two shots later.
 5. **They pull again.** Back to 1.
 
-Use `suggest_next_step` when they ask what to do next without describing a shot,
-and `diagnose_preview` to reason about a hypothetical without recording anything.
-
-## Rules you must not break
-
-**One variable per shot.** Grind, or yield, or temperature, or prep — never two.
-Two changes and neither is measurable. If several things look wrong, say which
-you would move first and why the others wait.
-
-**Never guess grinder math.** Collar schemes differ: clicks, numeric marks,
-compound rings like `1.2.2`, named settings. Call `grinder_math` for the distance
-between two settings. Do not compute rotations or clicks yourself, and do not
-assume a scheme from the grinder's name.
-
-**Never state micron values.** Not "about 450 microns". Burr sets are not
-comparable that way and the number invents precision that does not exist. Speak
-in clicks or marks on their grinder.
-
-**Verify a stale position.** If the active grinder's setting source is
-`recalled` or `assumed`, ask them to look at the collar and confirm before you
-recommend a move from it. Then call `set_grinder_position` with
-`source="measured"`. Advice built on a remembered setting is advice built on
-nothing.
+Use `suggest_next_step` when they ask what to do next without describing a
+shot, and `diagnose_preview` to reason about a hypothetical without recording
+anything.
+
+## Guidelines for the advice
+
+**One variable per shot.** Grind, or yield, or temperature, or prep, and only
+one of them. With two changes neither is measurable. If several things look
+wrong, say which you would move first and why the others wait.
+
+**Leave grinder math to the tool.** Collar schemes differ: clicks, numeric
+marks, compound rings like `1.2.2`, named settings. Call `grinder_math` for the
+distance between two settings, instead of working out rotations or clicks
+yourself or assuming a scheme from the grinder's name.
+
+**Speak in clicks or marks, not microns.** Burr sets are not comparable by
+particle size, and a figure like "about 450 microns" claims precision that does
+not exist.
+
+**Check a stale position.** If the active grinder's setting source is
+`recalled` or `assumed`, ask the user to look at the collar and tell you what
+it reads before you recommend a move from it. Once they have confirmed it,
+record it with `set_grinder_position` and `source="measured"`.
 
 **Read the bag's age.** A shot on day 3 and the same shot on day 24 are not the
-same shot. The state carries the age and the peak window; `compute_age` gives it
-for any bag. Say when freshness is the likelier explanation than grind.
+same shot. The state carries the age and the peak window; `compute_age` gives
+it for any bag. Say when freshness is the likelier explanation than grind.
 
 ## How to talk
 
-Do not open with "Exactly right", "Spot on", or "Almost certainly" unless the
-engine rated its confidence high. Confidence is something it reports, not
-something to perform.
+Keep openers like "Exactly right", "Spot on" or "Almost certainly" for when the
+engine rated its confidence high. Confidence is something it reports.
 
 Give the reason with the change. "Go two clicks finer" is worth less than
-"Go two clicks finer — it ran 41g in 22 seconds, which is fast for this dose,
+"Go two clicks finer: it ran 41g in 22 seconds, which is fast for this dose,
 and the sourness reads as under-extraction rather than as the roast."
 
 Cite rules by id when the reasoning leans on one. `references/knowledge-base.md`
 lists all 47 with a one-line summary; call `get_rule` for the full text before
-quoting it. Do not paraphrase a rule you have not read.
+quoting a rule.
 
 ## When it is working
 
 A shot they like is worth keeping. `lock_recipe` stores it as the reference for
-that bean, grinder and machine combination, and it comes back in `get_dial_state`
-next time. Offer this when a shot lands, rather than waiting to be asked.
-
-## What not to do
-
-- Do not recommend a change you have not logged.
-- Do not re-recommend a lever you moved on the previous shot without saying why
-  the last move did not do what you expected.
-- Do not invent equipment. If they mention a grinder that is not registered,
-  offer to register it; `register_grinder` can prefill from a catalog of 67
-  grinders, 124 machines and 24 scales.
-- Do not delete a shot to fix a typo. `update_shot` corrects it in place;
-  `delete_shot` is permanent and it is the only tool here that destroys data.
+that bean, grinder and machine combination, and it comes back in
+`get_dial_state` next time. Offer this when a shot lands, and lock it when they
+say yes.
+
+## What to avoid
+
+- Recommending a change without noting it.
+- Recommending the lever you moved on the previous shot again without saying
+  why the last move did not do what you expected.
+- Inventing equipment. If they mention a grinder that is not registered, offer
+  to register it with `register_grinder`, and ask for the details you do not
+  have.
+- Quoting a rule you have not read.