# Troubleshooting Symptom-based diagnosis tree for Local. ## Contents - Purpose - Standard pattern - General rules - Sour / sharp / thin - Bitter / harsh / drying - Flat / muddy / dull - Watery / weak - Too intense / too concentrated - Sour and bitter together - Gusher - Choke - Messy bottomless but tastes good - Graph does not match intended family - Too much clarity, not enough sweetness - Too much blending, not enough sparkle - Looks underextracted, but finer makes it worse - Nothing seems to work - Escalation guidance by family - Final rule of thumb ## Purpose Use this file when the user describes a taste or behavior problem and needs a structured next-step recommendation. The goal is not to dump every possible adjustment. The goal is to identify whether the main problem is: - **extraction**, - **strength**, - **evenness**, - or a mismatch between the coffee and the chosen **profile family**. ## Standard pattern Before troubleshooting, first ask whether the shot mainly has: 1. **failed family expression** 2. **basically successful family expression, but an unsatisfying taste target** Then, for each issue, reason in this order: 1. what kind of problem is this mainly? 2. what is the best first move? 3. what is the best second move if the first one fails? 4. when should we suspect puck prep, water, basket, freshness, or profile-family mismatch instead? If the main uncertainty is not the symptom itself but **which variable class to move next** — for example ratio vs pressure, flow vs family, or extraction vs strength vs evenness — use `extraction-levers.md`. This means troubleshooting is not only for obviously failed shots. It can also be used after a shot has basically expressed its intended family, when the user still wants the cup to move sweeter, clearer, fuller, softer, or otherwise closer to their taste target. ## General rules before any symptom-specific advice ### 1. One variable at a time If the shot is close, change one variable first. If the shot is a total disaster, larger moves are allowed — but still avoid changing everything blindly. ### 2. Use the family context A “bad” graph under one family may be normal under another. Do not troubleshoot a blooming, turbo, soup, or filter-style shot with rigid traditional 9-bar assumptions. ### 3. Taste outranks mythology Do not force a coffee into a famous recipe just because the recipe is popular. ### 4. If finer keeps making the shot worse, stop pushing finer That usually means the bottleneck is now evenness, puck stress, or family mismatch — not simply low extraction. --- ## 1. Sour / sharp / thin ### Usually means Most often this is one of: - too little useful extraction, - too little strength, - too little saturation, - or a family that is too clarity-biased for the coffee. ### First move If the cup is only a little sour but otherwise clean: - **extend ratio slightly** Why: - this is the simplest way to increase extraction without immediately increasing puck stress ### Second move If the cup is still sharp after a sensible ratio extension: - **grind slightly finer** But stop if: - the shot becomes more jagged, - bitterness appears without sweetness improving, - the graph becomes less stable, - or the cup gets both sour and bitter at once ### Other good moves depending on context - raise temperature slightly if structure is already sound - use a family with better wetting or blooming support for dense light coffees - consider a lower-pressure but higher-extraction family if high pressure is hurting evenness ### Suspect other causes when - the coffee is extremely fresh - the coffee is very dense and the family is too direct - the water is too soft or too sharp in presentation - the shot is visually unstable or tastes both sharp and messy --- ## 2. Bitter / harsh / drying ### Usually means This is often one of: - too much extraction, - too much puck stress, - too much pressure, - or uneven extraction showing up as harshness instead of sweetness. ### First move If the shot is otherwise structured and just too extractive: - **shorten ratio slightly** Why: - this reduces extraction load without changing puck mechanics first ### Second move If the cup is still bitter or especially drying: - **coarsen slightly** ### Other good moves depending on context - lower temperature slightly if the shot is otherwise healthy - lower pressure if the shot feels compressed, overstressed, or unstable - move away from a heavy / direct family toward a lower-compression family ### Suspect other causes when - the water is too hard or too buffered - the roast is more developed than expected - bitterness is paired with weird sourness → often an evenness issue, not just overextraction --- ## 3. Flat / muddy / dull ### Usually means This can come from: - too much blending, - poor clarity from low evenness, - stale coffee, - unsuitable water, - or a family that is too heavy for the coffee’s strengths. ### First move If the shot is technically balanced but boring: - **increase clarity by changing family or flow behavior** Typical options: - lower-pressure family - faster-flow family - turbo / allongé direction - filter-style or soup-adjacent direction if the coffee invites it ### Second move If family change is too large for now: - **slightly lengthen ratio or slightly increase functional flow** ### Other good moves depending on context - lower dose slightly if the puck is too thick and extraction is getting over-blended - revisit water if the coffee remains muted despite otherwise reasonable dialing - check bean age; old coffee often tastes flatter regardless of clever tuning ### Suspect other causes when - the coffee itself lacks vibrancy in cupping or brewed forms - the grinder is producing too much muddiness for the chosen style - the chosen family emphasizes body more than the coffee can support --- ## 4. Watery / weak ### Usually means This is mainly a **strength** issue, though extraction can also be too low. ### First move Ask whether the cup is: - weak but balanced, - or weak and sour / hollow. If weak but balanced: - **shorten ratio slightly** If weak and hollow: - **coarseness or low extraction may also be involved** ### Second move If shortening ratio makes it too intense but still not satisfying: - **grind a bit finer** - or consider a family with a little more body / integration ### Other good moves depending on context - raise dose slightly if basket and extraction headroom allow it - move away from an overly clarity-focused family if the coffee wants density ### Suspect other causes when - the coffee is simply not intense by nature - the brew is drifting out of the intended family (for example, soup brewed too coarse) --- ## 5. Too intense / too concentrated ### Usually means Mostly a **strength** problem, not automatically a bad extraction problem. ### First move - **extend ratio slightly** ### Second move If the shot becomes more open and sweet: - keep going in small steps If it becomes harsh instead: - the issue may not be concentration alone - inspect extraction structure, pressure, and family suitability ### Other good moves depending on context - switch from a body-heavy family toward a more clarity-heavy one - slightly reduce dose if the puck is excessively thick for the coffee --- ## 6. Sour and bitter together ### Usually means This is one of the strongest clues for an **evenness** problem. The puck is likely not being extracted uniformly. Some areas are underextracting while others are overextracting. ### First move - **do not immediately chase the flavor with larger ratio swings** - instead inspect puck prep, pressure stress, and family suitability ### Best first adjustment in many cases - **reduce puck stress** This may mean: - coarsen slightly - lower pressure - use a family with better wetting / soak support - improve puck prep ### Second move If the shot is still confused: - rethink whether the chosen family suits the coffee at all ### Suspect other causes when - the coffee is extremely fresh - the grinder is producing a lot of fines and instability - the shot is using a direct traditional family when the coffee wants blooming or lower-compression extraction --- ## 7. Gusher ### Usually means The puck is offering too little resistance, or the selected family is asking for a structure the grind cannot support. ### First move - **grind finer** ### Second move If it is still too fast: - consider increasing dose slightly - or use a family that creates a more gradual setup phase ### Important distinction Not every fast shot is a gusher. A successful turbo, allongé, or soup extraction may run quickly on purpose. What matters is whether it behaved like the intended family and whether the cup tastes coherent. ### Suspect other causes when - the basket / dose combination is inappropriate - distribution is so poor that resistance never forms evenly - the user is expecting traditional pressure from a deliberately low-pressure family --- ## 8. Choke ### Usually means The puck is too resistant for the chosen family and machine behavior. ### First move - **coarsen the grind** ### Second move If choking persists: - reduce dose slightly - lower pressure or reduce early puck stress - use a family with more supportive fill / soak behavior if the coffee is difficult ### Important note Some shots do not fully choke but are effectively over-restricted. These may still produce liquid, but taste dense, harsh, and structurally wrong. Treat them as “near choke” cases. --- ## 9. Messy bottomless but tastes good ### Usually means Possibly nothing is wrong. A visually ugly shot is not automatically a bad shot. This is especially true in: - fast low-pressure families, - light coffees, - high-clarity styles, - late-shot lower-viscosity behavior. ### First move - **trust the cup first** ### Second move If the messiness is paired with bitterness, astringency, or confusion: - then start troubleshooting evenness ### Rule Visual ugliness without sensory ugliness is weak evidence. --- ## 10. Graph does not match intended family ### Usually means Either: - the grind is wrong for the family, - the puck setup is wrong for the family, - the family is wrong for the coffee, - or the profile was misclassified to begin with. ### First move Ask: - what family was intended? - which part failed: wetting, ramp, main extraction, or taper? ### Then act accordingly - too much pressure too soon → usually too fine or too aggressive early setup - too little structure after setup → usually too coarse or too weak a setup phase - healthy family shape but bad taste → maybe the family is simply a poor match for the coffee ### Important note Do not force a family just because it is fashionable. If the coffee only tastes good in another family, that is a valid answer. --- ## 11. Too much clarity, not enough sweetness ### Usually means The shot may be too separated, too low in integration, or too “open” for the coffee. ### First move - move toward a slightly more integrating setup This may mean: - slightly shorter ratio - slightly slower functional flow - slightly more pressure - a move from turbo/filter-style toward fill-and-soak, blooming, or lever-like families ### Second move If sweetness still does not appear: - examine temperature and water ### Note Some coffees simply do not gain sweetness from more blending; they just become muddy. So move carefully. --- ## 12. Too much blending, not enough sparkle ### Usually means The shot may be too compressed, too pressure-heavy, or too contact-heavy for the coffee. ### First move - move toward a more open, clarity-biased setup This may mean: - longer ratio - lower pressure - faster functional flow - turbo / allongé direction - soup or filter-style direction for suitable coffees ### Second move If the shot becomes too weak: - use a more clarity-biased family, but recover some strength by dose or ratio tuning rather than going right back to high pressure --- ## 13. Looks underextracted, but finer makes it worse ### Usually means You have likely crossed from a simple extraction problem into an **evenness or stress** problem. ### First move - stop pushing finer ### Second move Choose one of: - reduce pressure - improve wetting / soak behavior - change family - slightly lower dose ### Rule When “more resistance” stops giving “more sweetness,” the answer is often not more resistance. --- ## 14. Nothing seems to work ### Usually means The hidden variable may be bigger than the visible one. ### Check these in order 1. **family mismatch** wrong style for the coffee 2. **water** especially if acidity is bizarrely sharp or everything is flat 3. **freshness** very fresh coffee can behave badly no matter how clever the recipe 4. **dose / basket geometry** puck thickness may be working against you 5. **thermal behavior** especially on long or high-flow extractions 6. **bean quality / roast quality** not every coffee can be dialed into greatness --- ## Escalation guidance by family ### Traditional / straight espresso If harsh or unstable: - reduce stress before assuming more grind restriction is needed ### Fill-and-soak / preinfusion-led If the post-soak phase feels wrong: - inspect whether the soak helped or merely delayed a bad grind setting ### Blooming If bloom improves saturation but the main shot still collapses: - check whether the bloom is too aggressive, too permissive, or simply the wrong tool for the coffee ### Lever-like / declining pressure If the decline never appears: - likely too fine or too restrictive If the decline becomes a collapse: - likely too coarse or too weakly structured ### Turbo / allongé If the shot tastes weak: - confirm whether it is truly a successful low-pressure fast-flow extraction or just a gusher ### Filter-style low-pressure If the shot tastes empty: - it may be too open, not simply “beautifully clear” ### Soup If the soak requires force or the brew behaves like pressured espresso: - you are likely too fine for the family If the puck offers no structure at all: - you may be too coarse and outside the soup regime ### Adaptive / resistance-led If everything feels random: - the profile may not actually be adaptive enough for the coffee, or the coffee may need a more intentionally shaped family --- ## Final rule of thumb When troubleshooting, ask these three questions before giving advice: 1. **What was this shot trying to be?** (family) 2. **What kind of failure is it?** (extraction, strength, evenness) 3. **What is the smallest smart next move?** (one variable, not a panic rewrite) If you answer those three cleanly, most bad shots become much easier to diagnose.