# Pitfalls Quick Reference Table

Quick lookup for all 13 pitfalls with severity, prevention, and phase mapping.

## Critical Pitfalls (v1 Must Address)

| # | Pitfall | Severity | Root Cause | Prevention | Phase | Detection |
|---|---------|----------|-----------|-----------|-------|-----------|
| 1 | **Barcode Mismatches & Duplicates** | CRITICAL | No fuzzy matching, no dedup | Canonical names + local dedup + fuzzy matching | v1 | Users report duplicate items (3x "Milk") |
| 2 | **Timezone & Expiration Bugs** | CRITICAL | Dates stored without UTC | Store all dates as UTC ISO 8601 | v1 | Item shows expired in one zone, fresh in another |
| 3 | **Multi-User Sync Conflicts** | CRITICAL | Last-Write-Wins naive strategy | Optimistic locking + version numbers | v1 | Concurrent updates silently lost; "I added it but it's gone" |
| 4 | **Setup Complexity** | CRITICAL | 15 required fields in MVP | 3-field MVP (name, location, expiry) | v1 | 50%+ onboarding dropout; "too complicated" reviews |
| 5 | **Notification Fatigue** | CRITICAL | Simple "if expires in N days, notify" | Snooze button + configurable timing | v1 | Users disable notifications entirely |

## Moderate Pitfalls (v1.5 Required)

| # | Pitfall | Severity | Root Cause | Prevention | Phase | Detection |
|---|---------|----------|-----------|-----------|-------|-----------|
| 6 | **Offline Sync Data Loss** | HIGH | Queue not persisted to disk | Persist queue locally + operation IDs | v1.5 | "I added items while offline and they disappeared" |
| 7 | **Barcode Scanner Failures** | HIGH | Low-quality scanner lib, no fallback | Robust lib (ML Kit/AVFoundation) + fallback + correction UI | v1.5 | "Scanned item is completely wrong"; low barcode feature usage |
| 8 | **Search/Item Lookup UX** | HIGH | Case-sensitive exact matching; no fuzzy | Full-text search + fuzzy matching + stemming | v1.5 | Users can't find items; high duplicate rate |
| 9 | **Insufficient Permissions** | HIGH | Binary permissions; no audit log | Clear role model + audit logging + ownership | v1.5 | Multi-user distrust; "who deleted my item?" |
| 10 | **Performance & Battery Drain** | MEDIUM | No indexing; syncs too frequently | Aggressive indexing + optimized syncing | v1.5 | Search >1s; app drains 10%+ battery/hour |

## Minor Pitfalls (v2 Deferred)

| # | Pitfall | Severity | Root Cause | Prevention | Phase | Detection |
|---|---------|----------|-----------|-----------|-------|-----------|
| 11 | **API Cost Surprises** | MEDIUM | Paid APIs without fallback | Use free APIs only in v1; plan fallback strategy | v2 | Bill grows faster than user base |
| 12 | **AI Prediction Overfitting** | LOW | Small sample size per user | Start simple; add ML only after 500+ items/user | v2 | Users turn off predictions; feature unused |
| 13 | **Community Spam & Privacy** | LOW | No moderation; data validation missing | Don't build community features in v1 | v2 | Spam in community data; privacy concerns |

---

## Phase Implementation Order

### v1 MVP (6-8 weeks)
**Non-negotiable:** Pitfalls 1, 2, 3, 4, 5
- Without barcode dedup, users lose trust
- Without UTC, timezone bugs kill reliability
- Without sync conflict handling, multi-user is broken
- Without simple onboarding, 50% abandon before first item
- Without notification control, users disable it and feature dies

### v1.5 Stabilization (4-6 weeks)
**Required for adoption:** Pitfalls 6, 7, 8, 9, 10
- Offline sync prevents data loss (trust issue)
- Barcode error handling prevents user frustration
- Better search prevents duplicate creation
- Permissions prevent multi-user conflicts
- Performance optimization keeps users engaged

### v2 Growth Phase (3-6 months)
**Only after v1 stable:** Pitfalls 11, 12, 13
- Community features need moderation (cost/effort)
- ML predictions need enough user data (not viable in v1)
- Cost surprises manageable after finding product-market fit

---

## Prevention Checklist for v1

Use this before launching MVP:

- [ ] **Barcode:** Implemented fuzzy matching on product names
- [ ] **Barcode:** Deduplication detects and merges duplicates
- [ ] **Barcode:** Uses USDA FoodData Central or Open Food Facts
- [ ] **Timezone:** All dates stored as UTC ISO 8601 (not just DATE type)
- [ ] **Timezone:** Tested expiration logic across 3+ timezones
- [ ] **Sync:** Implemented optimistic locking with version numbers
- [ ] **Sync:** Every operation has unique operation ID (idempotency)
- [ ] **Sync:** Concurrent edits tested and don't lose data
- [ ] **Onboarding:** First item requires only 3 fields (name, location, expiry)
- [ ] **Onboarding:** Measured and <20% onboarding dropout
- [ ] **Notifications:** Alert snooze button implemented
- [ ] **Notifications:** Alert timing configurable (default 3 days before expiry)
- [ ] **Notifications:** Dismissed alerts don't re-trigger for 24h minimum

---

## Detection Checklist (Weekly During Development)

Run this every sprint to catch pitfalls early:

- [ ] No user reports of "same item appears twice"
- [ ] Expiration tests pass across UTC, EST, PST, IST
- [ ] Concurrent update tests don't lose data
- [ ] 80%+ of users complete onboarding (add first item)
- [ ] 0 crashes during bulk operations
- [ ] Barcode scan fallback (manual entry) works
- [ ] Notification spam reports = 0
- [ ] Search latency <500ms on 100 items

---

## Implementation Priority Matrix

Use this to sequence feature work:

| Pitfall | Effort | Impact | Block Other Work? | Implement When |
|---------|--------|--------|-------------------|-----------------|
| Barcode dedup | Medium | Critical | Yes (data integrity) | Week 1 |
| UTC timestamps | Low | Critical | Yes (all date logic) | Week 1 |
| Optimistic locking | Medium | Critical | Yes (sync) | Week 2 |
| 3-field onboarding | Low | Critical | Yes (adoption) | Week 2 |
| Notification snooze | Low | Critical | Yes (retention) | Week 3 |
| Offline sync | Medium | High | No (can fallback) | v1.5 |
| Barcode errors | Medium | High | No (manual entry fallback) | v1.5 |
| Advanced search | Medium | High | No (basic search OK) | v1.5 |
| Permissions | Medium | High | No (owner-only OK) | v1.5 |
| Performance | Low | Medium | No (can optimize later) | v1.5 |
| API costs | Low | Medium | No (free tier OK) | v2 |
| ML predictions | High | Low | No (defer) | v2 |
| Community | High | Low | No (defer) | v2 |

---

## Real-World Reference

### Apps That Failed at These Pitfalls

**My Pantry Tracker:**
- Pitfall #2 (expiration date glitch preventing visibility)
- Pitfall #8 (search/categorization issues)

**FoodShiner:**
- Pitfall #7 (barcode scanner fails in split-view)
- Pitfall #7 (wrong product on scan)

**NoWaste:**
- Pitfall #4 (crashes during bulk operations - too many features)
- Pitfall #6 (data loss during crashes)

**Pantry Check:**
- Pitfall #4 (too many options, confusing export)

**CozZo:**
- Pitfall #6 (no offline fallback; app shut down when cloud shutdown)

---

## Sources

All prevention strategies backed by:
- 40+ researched sources
- 10+ app store reviews with specific complaints
- Real-world case studies (Sylius, Atlassian, GitHub)
- Distributed systems best practices
- User adoption research

See PITFALLS.md for full citations.