ShotPulled

View saved version →

---
name: shotpulled-dialing
description: Dial in espresso with ShotPulled. Use when someone describes a shot as sour, bitter, harsh, thin, fast, slow, choked or channeling, asks what to change on their grinder, wants to log a shot, or is dialing in a new bag of coffee. Diagnoses from taste, recommends one change at a time, and records both so the advice stays consistent. Requires the ShotPulled connector.
---

# Dialing in espresso

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

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

## How to talk

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

Referenced files: 4 — file references are metadata, not package contents.