fuel-price/docs/superpowers/specs/2026-04-15-tier-features-design.md

FuelAlert — Tier Feature Design (Free / Basic / Plus / Pro)

Context

The existing tier rules (.claude/rules/tiers.md) define notification channels per plan but not the information features that make each tier feel worth paying for. This spec closes that gap by cataloguing always-on information, personalisation, and analytics features — the value a user sees whether or not a notification fires — and mapping them to the four tiers. Triggered channel rules (email/push/WhatsApp/SMS) remain unchanged and are not redefined here.

Goals:

• Give each upgrade a concrete "what do I get for £X more" answer.
• Keep free tier useful enough to retain, but with clear ceiling.
• Keep Plus the commercial sweet spot (LLM prediction + fuel logs + MPG).
• Keep Pro genuinely premium (unlimited, multi-location, route planning, family sharing).

Teaser strategy: hybrid — headline features (prediction, extended history, detailed confidence) are visible but blurred with an upgrade CTA on Free; minor Pro-only features (route planner, family sharing) are hidden from lower tiers.

---

Feature Matrix

1. Fill-up recommendation (from AlertScoringService)

Feature	Free	Basic	Plus	Pro
Recommendation (fill_up / wait / no_signal)	✓	✓	✓	✓
Confidence % + reason string	—	✓	✓	✓
Per-signal breakdown (which of 5 signals fired, weights)	—	—	—	✓
Accuracy self-tracking ("our last wait call saved you Xp/L")	—	—	✓	✓

2. Oil price prediction (from price_predictions)

Feature	Free	Basic	Plus	Pro
Direction only (EWMA, no reasoning)	—	✓	✓	✓
Full LLM prediction (direction + confidence + reasoning)	—	—	✓	✓
Historical prediction accuracy view	—	—	—	✓

Rationale: Basic sees that prices are expected to rise/fall; Plus sees why.

3. Price history & trends

Feature	Free	Basic	Plus	Pro
Local price today	✓	✓	✓	✓
Price history chart	7 days	14 days	90 days	365 days
Brand comparison ("Tesco avg vs Shell avg near you")	—	—	✓	✓
Local price leaderboard (cheapest N nearby)	top 3 / 5km	top 5 / 5km	top 10 / 15km	top 20 / 50km

4. Saved data & personalisation

Feature	Free	Basic	Plus	Pro
Saved home postcode	✓	✓	✓	✓
Tracked fuel types	1	1	1	unlimited
Saved stations (favourites)	1	3	10	unlimited
Multiple locations (home/work/commute)	—	—	2	5
Custom price thresholds per fuel/station	—	1	3	unlimited

(Fuel-type cap for free/basic/plus matches existing tiers.md rule.)

5. Fuel logs & personal analytics (new)

Simple log: date, litres, price per litre, optional odometer.

Feature	Free	Basic	Plus	Pro
Log fill-ups (basic entry)	—	last 10	last 100	unlimited
MPG / cost-per-mile (needs odometer)	—	—	✓	✓
Monthly spend report	—	—	✓	✓
"You saved £X by following our advice" attribution	—	—	—	✓
CSV export of fuel log	—	—	—	✓

6. Tools (new, mostly Pro)

Feature	Free	Basic	Plus	Pro
Route planner — cheapest station along A→B	—	—	—	✓
Commute calculator — is the detour worth it?	—	—	—	✓
Family / household sharing (2 extra members on one account)	—	—	—	✓

---

Plan features JSON shape (additions)

Extend the existing features JSON in the plans table (see tiers.md for existing shape). New keys to add:

{
  "history_days": 7,
  "prediction": { "level": "none" },
  "recommendation": { "confidence_visible": false, "signal_breakdown": false, "accuracy_tracking": false },
  "leaderboard": { "count": 3, "radius_km": 5 },
  "saved_stations": { "max": 1 },
  "locations": { "max": 1 },
  "thresholds": { "max": 0 },
  "fuel_log": { "enabled": false, "max_entries": 0, "mpg": false, "monthly_report": false, "savings_attribution": false, "csv_export": false },
  "brand_comparison": false,
  "route_planner": false,
  "commute_calculator": false,
  "family_sharing": { "enabled": false, "max_members": 0 }
}

prediction.level values: none | direction (EWMA only) | full (LLM + reasoning) | full_with_accuracy (Pro).

Seeded values per tier

Key	Free	Basic	Plus	Pro
history_days	7	14	90	365
prediction.level	none	direction	full	full_with_accuracy
recommendation.confidence_visible	false	true	true	true
recommendation.signal_breakdown	false	false	false	true
recommendation.accuracy_tracking	false	false	true	true
leaderboard.count / radius_km	3 / 5	5 / 5	10 / 15	20 / 50
saved_stations.max	1	3	10	null (unlimited)
locations.max	1	1	2	5
thresholds.max	0	1	3	null
fuel_log.enabled	false	true	true	true
fuel_log.max_entries	0	10	100	null
fuel_log.mpg	false	false	true	true
fuel_log.monthly_report	false	false	true	true
fuel_log.savings_attribution	false	false	false	true
fuel_log.csv_export	false	false	false	true
brand_comparison	false	false	true	true
route_planner	false	false	false	true
commute_calculator	false	false	false	true
family_sharing.enabled / max_members	false / 0	false / 0	false / 0	true / 2

---

Out of scope (explicit)

• Implementation of route planner, commute calculator, brand comparison, family sharing — this spec gates them but their actual logic/UI is separate projects.
• Fuel log UI/import — separate project; this spec only defines the model and caps.
• Ads on free tier — dropped per user decision.
• Public API, shareable widgets, early access flags — dropped per user decision.