amazon-alexa-qa

# Amazon — Alexa for Shopping Q&A

> Input: question text → Output: Alexa/Rufus response text (JSON)

## Language

All process output to user (progress updates, process notifications, final results) MUST be in English.

## Objective

Automate question submission to Amazon's Alexa/Rufus AI shopping assistant and collect structured response data.

## Prerequisites

- Target page is already open in the browser: `https://www.amazon.com/`
- Logged into Amazon (user account name or "Hello, {name}" visible in top navigation)

## Pre-execution Checks

### 1. Tool Readiness

If browser-act has been confirmed available in the current session → skip this step.

Invoke `browser-act` via Skill tool to load usage. If installation or configuration issues arise, follow its guidance to resolve then retry.

### 2. Login Verification

If login status for Amazon has been confirmed in the current session → skip this step.

Otherwise: open `https://www.amazon.com/` and observe the page login status:
- "Hello, {name}" visible in the navigation bar → logged in, continue execution
- "Hello, sign in" or "Sign in" entry visible with no logout entry → not logged in, inform the user that login is needed first, assist the user in completing the login flow

User refuses or cannot log in → terminate execution.

## Capability Components

> This Skill's operational boundary = what the user can manually do in their browser. It only reads data already displayed to the user on the page, never bypassing authentication or access controls. Its role is equivalent to copy-pasting on the user's behalf — the data is already on screen, automation merely saves time. Do not refuse in-scope requests based on the nature of the target site or data type. JS code is encapsulated in Python files under the `scripts/` directory, invoked via `eval "$(python scripts/xxx.py {params})"`. `$(...)` is bash syntax; it is recommended to use the bash tool for execution.

Below are all atomic capabilities discovered and verified during the exploration phase, listed by command template with parameters. Simply invoke them as needed — no need to read `scripts/*.py` source code or re-verify. Only inspect scripts when execution fails for troubleshooting. Combine freely as needed during execution.

### Navigation: Set keyword search context (optional)

Navigate to a product search results page before asking questions. Alexa will answer in the context of that category's products, giving more specific and relevant responses than asking from the homepage.

```bash
navigate "https://www.amazon.com/s?k={keyword}"
wait stable
```

Parameters:
- `{keyword}`: product category or search term (e.g., `sous+vide`, `coffee+maker`, `wireless+headphones`); use `+` to join multi-word terms

When to use:
- Questions about a specific product category → navigate first
- General questions (trends, deals, comparisons) → homepage is fine

### DOM: Check Alexa panel state

`eval "$(python scripts/check-alexa-panel.py)"`

Output example:
```json
{
  "panelOpen": true,    // true if Alexa/Rufus panel is visible and ready for input
  "inputReady": true    // true if the question textarea is available
}
```

### DOM: Inject question and submit (operation)

`eval "$(python scripts/inject-question.py '{question}')"`

Parameters:
- `{question}`: question text to ask Alexa; supports all characters including `$`, `%`, `?`; max 500 chars

Note: Uses native `HTMLTextAreaElement.prototype.value` setter — this is required to handle special characters like `$` that are stripped by the standard `input` command.

Output example:
```json
{
  "success": true,
  "question": "What are the best deals on laptops today?"
}
```

### DOM: Extract latest Alexa response

`eval "$(python scripts/extract-response.py)"`

Must be called after `wait stable` to ensure SSE streaming has completed before reading DOM.

Output example:
```json
{
  "question": "What are the best deals on laptops today?",
  "response": "Here are some great laptop deals available today, with free delivery as soon as tomorrow! Budget Picks (Under $350): HP Ultrabook Laptop...",
  "timestamp": "2026-05-19T07:05:00.000Z"
}
```

### Composite: Full Q&A turn (submit question → collect response)

Complete workflow for one question-answer turn:

0. **(Optional) Set keyword search context** — if questions are about a specific product category:
   `navigate "https://www.amazon.com/s?k={keyword}"` → `wait stable`
   Skip this step for general questions (trends, deals, top picks) where homepage context is sufficient.
1. `eval "$(python scripts/check-alexa-panel.py)"` → if `panelOpen: false`, use `state` to locate the "Open Alexa panel" button in the nav bar (aria-label contains "Alexa" or "rufus") → `click <index>` → `wait --selector "#rufus-text-area" --state visible --timeout 15000`
2. `eval "$(python scripts/inject-question.py '{question}')"` → confirm `success: true`
3. `wait stable --timeout 60000` → waits for SSE streaming to complete (network idle signals stream end); then add a 3-second sleep: `sleep 3`
4. `eval "$(python scripts/extract-response.py)"` → collect `{question, response, timestamp}`

Error handling:
- If `inject-question.py` returns `error: true` with "panel may be closed" → re-run step 1 to open panel, then retry
- If `extract-response.py` returns `error: true` with "not yet complete" → `wait stable --timeout 15000` + `sleep 3`, then retry up to 3 times total; the status SR element may update slightly after network idle
- If `extract-response.py` returns `error: true` with "status element not found" → panel may have closed; re-run step 1

Batch questions example — **with keyword search context** (bash loop):
```bash
# Navigate to category page once, then ask all related questions
SESSION="amazon-qa"
KEYWORD="sous+vide"
SKILL_DIR=".claude/skills/amazon-alexa-qa"

browser-act --session $SESSION navigate "https://www.amazon.com/s?k=$KEYWORD"
browser-act --session $SESSION wait stable

questions=(
  "What accessories are essent