Diagnose espresso extraction issues by correlating machine telemetry with taste feedback. Use when user says: "what went wrong", "analyze that shot", "why did it taste [sour/bitter/flat]", "my shots are inconsistent", or asks about pressure spikes, flow issues, or extraction problems. Fetches shot data via analyze_shot MCP tool, interprets patterns, and provides actionable recommendations.
Diagnose espresso extraction issues by correlating Gaggimate telemetry data with taste feedback.
Adapted from gaggimate-barista by Charlie Hall.
Required inputs:
list_recent_shots if not provided)Fetch telemetry:
Use: analyze_shot(shot_id)
This returns diagnostics by default (resistance, channeling risk, temperature stability, profile compliance). If you need per-phase breakdowns or curve shape data, escalate progressively:
Use: analyze_shot(shot_id, detail="per_phase") # per-phase diagnostics (no samples)
Use: analyze_shot(shot_id, detail="per_phase_detailed") # per-phase diagnostics + ~5 averaged samples per phase
See the complete metric reference, annotation bands, and interpretation cheat sheet:
Use: read_knowledge(action="read", filename="diagnostics/SHOT_DIAGNOSTICS_REFERENCE")
Fetch shot notes if available:
Use: manage_shot_notes(shot_id, action="get")
Always ensure output weight is logged. If the shot notes or telemetry don't include dose out, ask the user: "What was the output weight in the cup?" The brew ratio is essential for diagnosis. Log it via manage_shot_notes(shot_id, action="update", dose_out=X) once obtained.
If the coffee being diagnosed is known, load its tracking file to check for patterns across recent shots:
manage_coffee(action="list")manage_coffee(action="read", coffee_name="<name>")Why this matters: Trend analysis helps distinguish between one-off puck prep issues and systematic dialing problems. For example, if the last 3 shots were all sour, that's a persistent under-extraction pattern requiring a larger grind adjustment — not a one-off fluke.
Before analyzing, identify the shot style so you compare against the right expectations. Use three tiers of detection (try in order, use first that succeeds):
Tier 1 — Fetch profile definition (preferred):
If analyze_shot returns a profile_id, fetch the full profile:
Use: manage_profile(action="get", profile_id=<profile_id>)
Classify by phase structure:
"target": "power" and "pressure": 0) → BloomTier 2 — Profile name keywords (fallback):
Match profile_name from analyze_shot:
Tier 3 — Telemetry fingerprint (last resort):
Load the telemetry patterns file and see the Style Detection Fingerprints section:
Use: read_knowledge(action="read", filename="diagnostics/TELEMETRY_PATTERNS")
Determine the final weight. Prefer telemetry data — load read_knowledge(action="read", filename="diagnostics/TELEMETRY_PATTERNS") for scale artifact detection and estimation methods. If telemetry is unavailable or looks unreliable (spikes, drops to 0g, nulls), ask the user for the actual weight.
State the dose out you're using and how you derived it, then move on.
Load style-specific expectations from read_knowledge(action="read", filename="PRESSURE_GUIDE") (Pressure by Shot Style) and read_knowledge(action="read", filename="PROFILE_LIBRARY") (Quick Reference table). Compare telemetry against style-specific ranges — not generic 9-bar ranges.
Universal thresholds (style-independent):
| Metric | Normal | Anomaly |
|---|---|---|
| Temperature variance | ±1°C from target | >2°C = equipment instability |
| Pressure spike above profile target | — | >1.0 bar above = almost certainly too fine / channeling (>0.5 unusual) |
Flag an anomaly only when a metric falls outside the identified style's expected range.
Profile compliance metrics are included in the diagnostics automatically when target pressure/flow data is in the shot. Key fields:
pressure_rmse_bar — how closely the machine followed target pressure (lower = better)max_pressure_overshoot_bar — largest single overshoot above targetflow_rmse_ml_s — flow adherence (when target flow data available)max_flow_overshoot_ml_s — largest flow above target (when target flow data available)max_flow_undershoot_ml_s — largest flow below target (when target flow data available)Grind diagnosis priority: Flow deviation is a more reliable grind indicator than pressure overshoot. The Gaggimate/gaggiuino PID actively controls pump power to maintain target pressure, so pressure overshoot is artificially limited by the controller. Flow rate is a consequence of grind + dose + puck prep and cannot be masked by the pump — making
max_flow_overshoot_ml_s/max_flow_undershoot_ml_sthe stronger signal for grind mismatch. Always check flow deviation first when diagnosing grind issues.
| Comparison | Interpretation |
|---|---|
max_flow_overshoot_ml_s > 0.7 | Grind too coarse — flow significantly above target (strongest grind signal) |
max_flow_undershoot_ml_s > 0.7 | Grind too fine — flow significantly below target (strongest grind signal) |
max_pressure_overshoot_bar > 1.0 | Grind too fine — machine can't push water through puck (>0.5 already unusual) |
max_pressure_undershoot_bar > 1.0 (non-bloom context) | Grind too coarse |
pressure_rmse_bar annotation POOR | Profile not being followed — check grind, dose, or profile params |
| Pressure exceeded target by >1.0 bar | Grind too fine or dose too high (highly unusual overshoot) |
| Pressure never reached target (>1.0 bar below) | Context-dependent: normal for post-bloom ramps, too coarse for non-bloom |
| Volumetric target reached much earlier than phase duration | Grind too coarse (flow too fast) |
| Volumetric target not reached within phase duration | Grind too fine (flow too slow) |
| Decline phase pressure stayed >1 bar above target floor | Grind too fine — high puck resistance |
Cross-reference the user's taste feedback with telemetry patterns.
See: read_knowledge(action="read", filename="diagnostics/TELEMETRY_PATTERNS") for detailed correlation matrix and read_knowledge(action="read", filename="diagnostics/DIAGNOSTIC_TREES") for taste-based decision trees.
Provide specific, prioritized recommendations:
Always explain WHY each recommendation addresses the diagnosed issue.
## Shot Analysis: [Shot ID]
### Identified Style: [Style Name]
(detected via [Tier 1: profile definition / Tier 2: profile name / Tier 3: telemetry fingerprint])
### Telemetry Summary
- **Pressure:** [peak] bar (style expects: X-Y bar)
- **Flow:** [avg] ml/s, first drip at [X]s (style expects: A-B ml/s)
- **Temperature:** [avg]°C (target: X°C, variance: ±X°C)
- **Timing:** [total]s total (style expects: E-Fs)
### Phase Comparison (if profile definition available)
[Intended vs actual for each phase — pressure, flow, timing]
### Diagnosis
[Correlation between telemetry and reported taste, interpreted through style-specific expectations]
### Recommendations
1. **[Primary fix]** — [specific action with reasoning]
2. **[Secondary fix]** — [backup if primary doesn't work]
3. **[Profile consideration]** — [if applicable]
### What to Watch For
[What user should observe on next shot to confirm diagnosis]