shopping-assistant

# Shopping Assistant

A systematic, multi-phase shopping research workflow that acts as the user's personal shopping advisor. The goal is to save the user hours of research by running a thorough, structured product comparison pipeline — from initial requirements gathering through final recommendation with 3-4 best options.

## Why This Workflow Matters

Most people either under-research (buy the first thing they see) or over-research (spend days in analysis paralysis). This workflow hits the sweet spot: thorough enough to avoid regret, structured enough to converge on a decision. Each phase builds on the previous one, and the process is designed to catch blind spots that casual browsing misses.

## Phase Overview

The workflow has 10 phases. Move through them sequentially, but adapt pace to the user's engagement level. Some phases can be compressed for low-stakes purchases (under ~$50), while high-stakes purchases deserve the full treatment.

```
1. DISCOVER  → What does the user need? Where?
2. DEFINE    → What features matter? Prioritize them.
3. SURVEY    → First list of candidates with ratings.
4. COMPARE   → Head-to-head comparisons reveal hidden features.
5. OPTIMIZE  → Find better value within same brands.
6. EXPAND    → Check alternatives from other brands.
7. NARROW    → Final shortlist of 3-4 options.
8. REVIEW    → Deep dive into reviews for shortlisted items.
9. STRETCH   → One last check: premium or budget alternatives?
10. DECIDE   → Resale value, delivery, final recommendation.
```

---

## Research Tools — Preferred Order

When available, InfraNodus tools provide structured insights that web search alone often misses — real buyer search patterns, demand-supply gaps, and structural blind spots in the market discourse. For each research phase, **start with the InfraNodus tool call first**, then supplement with web search to fill in specific product details, prices, and reviews. If InfraNodus tools are not available, fall back to web search alone.

| Phase      | InfraNodus Tool (start here)                                              | Then Web Search For                                     |
| ---------- | ------------------------------------------------------------------------- | ------------------------------------------------------- |
| 2. DEFINE  | `analyze_related_search_queries` — discover features buyers care about    | Filter categories on shopping sites, review pain points |
| 3. SURVEY  | `search_queries_vs_search_results` — find what people want but can't find | Specific product specs, prices, availability            |
| 4. COMPARE | `generate_content_gaps` — find blind spots across review content          | Head-to-head comparison articles                        |
| 6. EXPAND  | `generate_research_ideas` (shouldTranscend) — lateral alternatives        | Alternative product categories                          |

This order matters: InfraNodus surfaces patterns across many searches at once, revealing gaps that sequential web searches tend to miss. Web search then grounds those insights in specific, current product data.

---

## Phase 1: DISCOVER — Understand What the User Needs

Start every shopping conversation by understanding two things:

1. **What product** does the user want to buy? Get specific: not just "laptop" but "laptop for video editing" or "laptop for my kid starting college."
2. **Where** will they buy it? This affects availability, pricing, delivery, and warranty. Ask for their country/city if not already known from context.

Ask these questions conversationally. If the user already provided context (e.g., "I need a new dishwasher"), acknowledge it and ask the missing pieces.

Also probe lightly for:

- **Budget range** (even approximate: "under $500" or "mid-range" is fine)
- **Timeline** (do they need it this week, or can they wait for sales?)
- **Any brand preferences or exclusions** ("I've had bad luck with X")
- **Where they'll use it** (environment, frequency, conditions)

Don't overwhelm — 2-3 questions max in the first message. You can gather more context as you go.

---

## Phase 2: DEFINE — Build the Feature Priority List

This is the most important phase. A good feature list prevents wasted research.

Build the requirements from three sources:

### Source A: User's Own Requirements

Extract from what they've already said. Ask follow-up questions for anything ambiguous. These are highest priority since they come directly from the user.

### Source B: Filters on Major Shopping Sites

Search the web for the product category on 2-3 major specialized shopping sites relevant to the product and location. Look at what filter categories they offer — these represent the features that matter most to buyers in this category.

```
Example: For headphones, a site might filter by:
- Type (over-ear, in-ear, on-ear)
- Wireless vs wired
- Noise cancellation
- Battery life
- Driver size
- Impedance
```

Extract the filter categories that seem relevant to this user's needs.

### Source C: Review Pain Points and Pleasure Points

Search for "[product category] common complaints" and "[product category] most loved features." Look for recurring themes in what makes people happy or unhappy with products in this category. These reveal features the user might not have thought to ask about but will care about once they encounter them.

```
Example: For robot vacuums, common pain points include:
- Gets stuck on dark carpets
- App requires account creation
- Loud operation
- Poor mapping of multi-floor homes
```

### Source D: Demand-Side Signal Analysis (InfraNodus) — Start Here

Before diving into web searches for pain points and filter categories, call `analyze_related_search_queries` with 2-3 queries describing the product category (e.g., ["4K projector", "home cinema projector", "short throw projector"]). Set the language and country to match the user's location. This single call often surfaces features, brand names, and buyer concerns that would take 5-10 we