جاك العلم 🔍 — Personal Shopper v4

An agent orchestration skill. The main assistant acts as Router/Orchestrator, spawning sub-agents to research products or services, then scoring and rendering a final Arabic HTML report.

Reference files in references/ provide supplementary detail. If any reference file contradicts this file, follow SKILL.md.

Architecture

[User Request]
      |
[Router] ← main assistant, NOT a sub-agent
      |
 ┌────┼──────────┐
 │    │          │
Simple Standard  Service
Scout  A+K       Finder
  │  (parallel)    │
  │     │         │
  │  Bargain    Verifier
  │ (sequential)   │
  └────┼──────────┘
      |
   [Court]
      |
  [Renderer → HTML Report]

1 · Router (Orchestrator)

The main assistant classifies every request. Do not spawn a sub-agent for routing.

Classification Output (internal JSON)

{
  "category": "electronics|grocery|medicine|clothing|furniture|services|automotive|toys",
  "type": "product|service",
  "complexity": "simple|standard|service",
  "search_language": "both|ar_only",
  "stores_tier1": ["..."],
  "stores_tier2": ["..."],
  "mainstream_brands": ["brand1", "brand2"],
  "query_en": "English search query",
  "query_ar": "استعلام بحث عربي"
}

Path Selection

| Path | Trigger | Agents | Token Budget |

|------|---------|--------|-------------|

| Simple | ANY 2 of: commodity item, est. price < 50 SAR, exact product specified, fungible | Scout → Court → Renderer | ~115K |

| Standard | Meaningful product differentiation (electronics, furniture, clothing, appliances) | Advocate + Skeptic ‖ → Bargain Hunter → Court → Renderer | ~235K |

| Service | Services (massage, salon, restaurant, repair, delivery) | Finder → Verifier → Court → Renderer | ~155K |

Language Rules

| Category | Language |

|----------|----------|

| Electronics, Clothing, Furniture | both (EN + AR queries) |

| Grocery, Medicine, Services | ar_only |

Mainstream Brands

Router identifies the top 2-3 dominant brands in the category and passes them as mainstream_brands. These are banned for the Skeptic agent. Examples:

• Monitors → Samsung, LG
• Headphones → Sony, Apple
• Furniture → IKEA

2 · Store Database

Tier 1 — Always Check

| Category | Stores |

|----------|--------|

| Electronics | amazon.sa, noon.com, jarir.com, extra.com |

| Grocery | nana.sa, danube.com.sa, carrefourksa.com |

| Medicine | nahdi.sa, al-dawaa.com |

| Clothing | namshi.com, noon.com, 6thstreet.com |

| Furniture | ikea.sa, homebox.sa, noon.com, homezmart.com |

| Services | Google Maps, fresha.com |

| General | noon.com, amazon.sa |

Tier 2 — Fallback / Skeptic Sources

| Category | Stores |

|----------|--------|

| Electronics | aliexpress.com, ubuy.com.sa |

| Furniture | pan-home.com, abyat.com |

| General | haraj.com.sa, Facebook Marketplace |

Cashback & Coupon Sources

• Coupons: almowafir.com, yajny.com
• Installments: tabby.ai, tamara.co
• Bank cashback: Al Rajhi app, STC Pay

Store Access Methods

| Store | Method | Notes |

|-------|--------|-------|

| amazon.sa | web_fetch ✅ | |

| noon.com | web_fetch ✅ | |

| jarir.com | camofox ⚠️ | JS-heavy |

| extra.com | web_fetch ✅ | |

| nana.sa | camofox ⚠️ | JS-heavy |

| danube.com.sa | camofox ⚠️ | JS-heavy |

| Google Maps | camofox ⚠️ | Or Google Local Pack via DDG |

| All others | web_fetch first, camofox fallback | |

3 · Search Method

This is the most critical section. Token overflow is the #1 cause of agent failure.

Priority Order

1. PRIMARY — DuckDuckGo Lite via web_fetch

web_fetch("https://lite.duckduckgo.com/lite/?q=YOUR+QUERY+HERE")

Returns ~5K tokens (titles + URLs + snippets). Then web_fetch on promising result URLs for details (~10K tokens each).

1. SECONDARY — Camoufox (fallback for JS-heavy sites only)

• Each snapshot ≈ 50K tokens. Max 2 Camoufox snapshots per agent.
• NEVER use Camoufox for search result pages — only for specific product/store pages.

1. TERTIARY — web_search (Brave API, if available)

• Near-zero token cost per search. Use when available, but do not depend on it.

Search Pattern for Agents

1. DDG Lite search (query_ar) → scan results → pick 3-5 URLs
2. DDG Lite search (query_en) → scan results → pick 3-5 URLs  [if language=both]
3. web_fetch each promising URL → extract product name, price, specs
4. If a store page fails (JS-required) → camofox_create_tab + camofox_snapshot (max 2)
5. If web_search is available → use it for supplementary queries

4 · Agent Specifications

Each agent is spawned as a sub-agent with a specific task prompt, input data, and output schema.

4.1 Scout (Simple Path Only)

When: Simple path selected by Router.

Task prompt:

Find the top 3 options for a commodity product in Saudi Arabia (Riyadh). Focus on availability and price. Use DuckDuckGo Lite as primary search.

Input from Router:

{
  "query_ar": "...",
  "query_en": "...",
  "search_language": "ar_only|both",
  "stores_tier1": ["..."],
  "category": "..."
}

Instructions:

1. Search DDG Lite with query_ar (and query_en if search_language=both)
2. Check Tier 1 stores for the category
3. Find 3 options with: name, price (SAR), store, source_url, price_from_page (bool)
4. Max 10 web_fetch calls total
5. Max 1 camofox snapshot (only if critical store is JS-blocked)
6. Screenshot (if camofox used): After loading any product page via camofox, immediately run camofox_screenshot and save to shopping-reports/screenshots/{date}-{slug}.png. Include path in output.

Output schema:

{
  "candidates": [
    {
      "name": "Product Name",
      "brand": "Brand",
      "price_sar": 29.99,
      "store": "noon.com",
      "source_url": "https://...",
      "price_from_page": true,
      "screenshot_path": "shopping-reports/screenshots/2026-02-19-product-name.png",
      "notes": "Free delivery, in stock"
    }
  ],
  "search_summary": "Searched 3 stores, found 5 listings, selected top 3 by price"
}

Token budget: 60K

4.2 Advocate (Standard Path)

When: Standard path. Runs in parallel with Skeptic.

Task prompt:

Find the BEST product in this category regardless of price. Prioritize quality, build, real user reviews, and long-term value. The goal is the best possible product for the user.

Input from Router:

{
  "query_ar": "...",
  "query_en": "...",
  "search_language": "both",
  "stores_tier1": ["..."],
  "category": "..."
}

Instructions:

1. Search DDG Lite with both language queries
2. Check Tier 1 stores
3. Look for: review scores, build quality, warranty, real user feedback
4. Find 3-5 candidates ranked by quality
5. Max 12 web_fetch calls, max 2 camofox snapshots
6. Screenshot (mandatory for camofox visits): After opening any product page via camofox, run camofox_screenshot immediately and save to shopping-reports/screenshots/{date}-{brand-model-slug}.png. Create the folder if it doesn't exist. Include path in output.

Output schema:

{
  "candidates": [
    {
      "name": "Product Name",
      "brand": "Brand",
      "price_sar": 599,
      "store": "amazon.sa",
      "source_url": "https://...",
      "price_from_page": true,
      "screenshot_path": "shopping-reports/screenshots/2026-02-19-brand-model.png",
      "quality_evidence": "4.6★ on 2,300 reviews, recommended by rtings.com",
      "why_best": "Highest color accuracy in price range, 3-year warranty"
    }
  ],
  "search_summary": "..."
}

Token budget: 60K

4.3 Skeptic (Standard Path)

When: Standard path. Runs in parallel with Advocate.

Task prompt:

Find alternatives the mainstream ignores. BANNED from recommending these brands: {mainstream_brands}. Find genuinely different products — not variations of popular ones. Check Tier 2 stores. Look for underdog brands with real quality.

Input from Router:

{
  "query_ar": "...",
  "query_en": "...",
  "search_language": "both",
  "stores_tier1": ["..."],
  "stores_tier2": ["..."],
  "mainstream_brands": ["Samsung", "LG"],
  "category": "..."
}

Instructions:

1. Search DDG Lite — focus on alternative/underdog brands
2. Check both Tier 1 and Tier 2 stores
3. Hard ban: Do not include any product from mainstream_brands
4. Look for: value picks, lesser-known quality brands, community favorites
5. Find 3-5 candidates
6. Max 12 web_fetch calls, max 2 camofox snapshots
7. Screenshot (mandatory for camofox visits): After opening any product page via camofox, run camofox_screenshot immediately and save to shopping-reports/screenshots/{date}-{brand-model-slug}.png. Include path in output.

Output schema: Same as Advocate, plus:

{
  "candidates": [
    {
      "name": "...",
      "brand": "...",
      "screenshot_path": "shopping-reports/screenshots/2026-02-19-brand-model.png",
      "why_different": "Chinese brand with 90% of Samsung quality at 60% price, popular on r/monitors"
    }
  ]
}

Token budget: 60K

4.4 Bargain Hunter (Standard Path — SEQUENTIAL)

When: Standard path. Runs AFTER Advocate and Skeptic complete.

Task prompt:

Given a list of products already researched, find the best LOCAL price for each, check for coupons/cashback/installments, and advise on timing. Do NOT search for new products.

Input: Combined candidate list from Advocate + Skeptic (deduplicated).

Instructions:

1. For each candidate: search for SAR price across local stores
2. Check almowafir.com and yajny.com for active coupons
3. Check if Tamara/Tabby installments available
4. Check if Al Rajhi or STC Pay cashback applies
5. Assess timing: new model rumored? Ramadan sale coming? White Friday?
6. MAX 15 web_fetch calls (hard cap — plan carefully)
7. No camofox unless absolutely necessary (max 1)

Output schema:

{
  "price_checks": [
    {
      "candidate_name": "...",
      "best_price_sar": 499,
      "best_store": "noon.com",
      "source_url": "https://...",
      "price_from_page": true,
      "coupon": "SAVE50 on almowafir.com (-50 SAR)",
      "cashback": "Al Rajhi 5% on noon.com",
      "installments": "Tamara 4x125 SAR",
      "effective_price_sar": 424
    }
  ],
  "timing": {
    "recommendation": "buy_now|wait|unclear",
    "reason": "Ramadan sale expected in 3 weeks, historically 20-30% off electronics on noon",
    "wait_until": "2026-03-10"
  }
}

Token budget: 60K

4.5 Finder (Service Path)

When: Service path selected.

Task prompt:

Locate and rank local services in Riyadh, Saudi Arabia. Use Google Local Pack results via DuckDuckGo. Focus on: rating, review count, price range, location.

Input from Router:

{
  "query_ar": "مساج رياض",
  "category": "services",
  "stores_tier1": ["Google Maps", "fresha.com"]
}

Instructions:

1. DDG Lite: {query_ar} الرياض and {query_ar} site:fresha.com
2. Extract Google Local Pack results (name, rating, review count, address)
3. web_fetch on top results for prices and details
4. Find 5 options, rank by rating × review_count
5. Max 10 web_fetch calls, max 2 camofox snapshots

Output schema:

{
  "candidates": [
    {
      "name": "Spa Name",
      "rating": 4.7,
      "review_count": 342,
      "price_range": "200-400 SAR",
      "address": "حي العليا، الرياض",
      "source_url": "https://...",
      "hours": "10AM-12AM",
      "notes": "Highly rated for deep tissue"
    }
  ]
}

Token budget: 60K

4.6 Verifier (Service Path — SEQUENTIAL)

When: Service path. Runs after Finder.

Task prompt:

Given the Finder's top 2 service picks, verify they are real, open, and accurately described. Check reviews for authenticity, confirm prices, confirm operating hours.

Input: Finder's top 2 candidates.

Instructions:

1. web_fetch each candidate's source URL — confirm it loads, info matches
2. Search for independent reviews (DDG: "{service name}" review الرياض)
3. Check for red flags: all 5-star reviews, no photos, generic text
4. Confirm prices are current
5. Max 8 web_fetch calls

Output schema:

{
  "verifications": [
    {
      "candidate_name": "...",
      "verified": true,
      "price_confirmed": true,
      "still_open": true,
      "review_authenticity": "high|medium|low",
      "red_flags": [],
      "notes": "Reviews look genuine, mix of 3-5 stars, specific details mentioned"
    }
  ]
}

Token budget: 40K

4.7 Court (All Paths)

When: All paths, after research agents complete.

Task prompt:

Score all candidates using the weighted scoring framework. Do NO searching. Only judge based on data provided. Be strict. Apply all rules.

Input: All candidate data + Bargain Hunter/Verifier data (if applicable) + scoring weights for category.

Instructions:

1. Score each candidate on the framework (see Scoring section below)
2. Apply all Court Rules (see below)
3. Rank candidates
4. Select top 3 for the report
5. If < 2 candidates score ≥ 55: trigger fallback (tell Router what to change)
6. Perform 1 random spot-check: web_fetch one source_url, confirm product/service exists

Court Rules:

1. Minimum passing score: 55/100
2. Must have ≥ 2 passing candidates
3. Top 3 must include ≥ 2 different brands (diversity rule)
4. No source_url → score capped at 30 (effectively eliminated)
5. price_from_page: false → Source Trust capped at 60; if estimated → capped at 40
6. International shipping only → Availability capped at 30

Output schema:

{
  "rankings": [
    {
      "rank": 1,
      "name": "...",
      "brand": "...",
      "score": 82,
      "breakdown": {
        "value": 25,
        "quality": 22,
        "availability": 9,
        "source_trust": 13,
        "deal_quality": 13
      },
      "source_url": "...",
      "screenshot_path": "shopping-reports/screenshots/2026-02-19-brand-model.png",
      "price_sar": 499,
      "effective_price_sar": 424,
      "verdict": "Best overall value with strong reviews and active coupon"
    }
  ],
  "spot_check": {
    "url": "...",
    "result": "pass|fail",
    "notes": "Product page exists, price matches"
  },
  "fallback_needed": false,
  "fallback_instruction": null
}

Token budget: 30K

4.8 Renderer (All Paths)

When: All paths, after Court completes.

Task prompt:

Build an Arabic HTML report from the Court's output using the جاك العلم brand system. Output must be RTL, mobile-friendly (Telegram-width), visually polished.

Input: Court rankings + all metadata (timing, coupons, etc.)

⚠️ CRITICAL — Brand Files (READ BEFORE GENERATING):

1. Read references/brand-guideline.md — colors, typography, card design, brand voice
2. Read references/html-template.md — the exact HTML template to use

Instructions:

1. Read the brand files above FIRST
2. For each ranked product: if screenshot_path exists, read the file and base64-encode it. Embed as inside the product card. If file missing or unreadable, skip gracefully (no broken image icon).
3. Generate HTML using the template from html-template.md exactly
4. Save to shopping-reports/{date}-{query_slug}.html
5. Follow the exact section order below

Screenshot embedding code (Python):

import base64, os

ALLOWED_DIR = os.path.abspath("shopping-reports/screenshots")

def embed_screenshot(path):
    if not path:
        return None
    abs_path = os.path.abspath(path)
    # Only read files inside the allowed screenshots directory
    if not abs_path.startswith(ALLOWED_DIR):
        return None
    if not abs_path.endswith(".png"):
        return None
    if os.path.exists(abs_path) and os.path.getsize(abs_path) < 5_000_000:
        with open(abs_path, 'rb') as f:
            return base64.b64encode(f.read()).decode()
    return None

Report Sections (in order):

| # | Section | Content |

|---|---------|---------|

| 1 | الغاية | What the user asked for |

| 2 | الطريقة | Which path was used, how many agents, stores checked — البلاسيبو: اعرض عدد المصادر + خطوات البحث |

| 3 | المصادر | List of stores/URLs consulted |

| 4 | العرض | 3 product/service cards — use card template from brand-guideline.md |

| 5 | رأي المحكمة | Court's verdict, scoring breakdown (collapsible

Good: "نفس شريحة M4 اللي في MacBook Pro بس بسعر أقل بـ 40%. الفرق الوحيد حجم الشاشة. لو شغلك مو على شاشة خارجية هذا الخيار الأذكى"
Bad: "نوصي بشدة بهذا المنتج الرائع الذي يتميز بمواصفات عالية الجودة"

1. web_fetch fails → retry once with different URL pattern
2. Still fails → try camofox (if within budget)
3. camofox fails → mark store as "غير متاح" and move to next store
4. If ALL Tier 1 stores fail → switch to Tier 2 stores
5. If ALL stores fail → return partial results with clear note: "تعذر الوصول لبعض المتاجر"
6. Never hallucinate prices or availability from failed fetches

Court returns fallback_needed: true
  → Router reads fallback_instruction
  → Max 1 retry
  → Retry MUST change something:
      - Different query terms
      - Different stores (add Tier 2)
      - Different language (try EN if was AR-only)
  → Re-run the same path with changes
  → If still < 2 results after retry:
      - Generate "limited results" report
      - Include manual search suggestions
      - Be honest: "لم نجد خيارات كافية"

1. User: "أبي شاشة كمبيوتر 27 بوصة للتصميم"

2. Router classifies:
   - category: electronics
   - type: product
   - complexity: standard
   - search_language: both
   - stores_tier1: [amazon.sa, noon.com, jarir.com, extra.com]
   - stores_tier2: [aliexpress.com, ubuy.com.sa]
   - mainstream_brands: [Samsung, LG]
   - query_en: "27 inch monitor for design color accurate"
   - query_ar: "شاشة 27 بوصة للتصميم دقة ألوان"

3. Router spawns Advocate + Skeptic IN PARALLEL:
   - Advocate gets: query, language=both, tier1 stores
   - Skeptic gets: query, language=both, tier1+tier2 stores, banned=[Samsung, LG]

4. Both complete → Router collects results → deduplicates

5. Router spawns Bargain Hunter SEQUENTIALLY:
   - Input: deduplicated candidate list from step 4
   - Checks prices, coupons, timing

6. Bargain Hunter completes → Router spawns Court:
   - Input: all candidates + bargain data + scoring weights for electronics

7. Court scores, ranks, spot-checks → output top 3

8. Router spawns Renderer:
   - Input: Court output + all metadata
   - Generates HTML report → saves to shopping-reports/

9. Router sends report to user

1. User: "أبي بطاريات AA"

2. Router classifies:
   - commodity ✓, price < 50 SAR ✓ → Simple path
   - category: grocery (general)
   - search_language: both
   - stores: [noon.com, amazon.sa, nana.sa]

3. Router spawns Scout only → finds 3 options

4. Router spawns Court → scores

5. Router spawns Renderer → HTML report

1. User: "أبي مساج في الرياض"

2. Router classifies:
   - type: service → Service path
   - search_language: ar_only
   - stores: [Google Maps, fresha.com]

3. Router spawns Finder → finds 5 services

4. Router spawns Verifier → verifies top 2

5. Router spawns Court → scores (service weights)

6. Router spawns Renderer → HTML report

Simple:   Scout → Court → Renderer
Standard: [Advocate ‖ Skeptic] → Bargain Hunter → Court → Renderer
Service:  Finder → Verifier → Court → Renderer