product-research

Run persists to ~/Documents/Research/ in the same format as the generic research skill, with a product-specific synthesis structure. </objective>

<core_rules>

1. One product per run. If the invocation mentions multiple products, push back — do not silently pick one.
2. Research-derived criteria supersede user priorities. User priorities are input signal + tiebreaker only. Contradictions with 2+ quality sources become master-class teaching moments.
3. No --recency flags on CLI calls. Mature products have valid older reviews. Use verification scrape instead.
4. Availability tiering: Green (RO retailer) → full recommend. Yellow (EU retailer, Amazon DE / Bol.nl / etc.) → recommend, flag import. Red (US-only / non-EU) → exclude.
5. Never invent a tier to fill a slot. Substitute the tier name with a use-case axis, or omit the tier.
6. Scrape-only verification. Flag recommendations — never rewrite them based on verification result.
7. Stage order is sequential. Preliminary (Stage 2) — including aspect discovery, deep-dives, and masterclass assembly — must finish before Product phase (Stage 3) spawns. Product subagents consume the ranked criteria extracted from the masterclass. </core_rules>

<shared_infrastructure> This skill reuses the research skill's infrastructure via cross-reference. Do not duplicate these:

• CLI commands — see ../research/references/cli-reference.md for ask, search, reason, scrape, docs, youtube, social reddit invocations
• Angle file frontmatter + run directory layout — see ../research/references/persistence-format.md
• Subagent spawning — use the Task tool with subagent_type: "research-subagent" (has API logging hooks). Same pattern as the research skill.
• Output directory — ~/Documents/Research/

Differences from generic research:

• Staged pipeline (5 sequential stages) instead of single parallel spawn
• Slug convention: YYYY-MM-DD-<category>-product-research (e.g., 2026-04-23-microwave-product-research)
• Synthesis file uses product-specific structure (see references/synthesis-template.md) </shared_infrastructure>

<trigger_and_routing> This skill runs only via explicit invocation (/product-research).

If the invocation message mentions multiple products, respond:

Product research runs one product at a time so we can go deep on criteria, market, and availability. You mentioned [X] and [Y] — which one should we start with? I'd suggest running the second in a fresh session when you're ready, so each gets full focus and its own persisted research folder.

If the invocation is ambiguous about which product is the subject (e.g., user discussed several in conversation), ask once via AskUserQuestion which category to research.

Out of scope — redirect to generic /research:

• "Should I keep my current X or replace it?" (replacement analysis — different pipeline)
• "Tell me about X" / "how does X work" (educational, not buying)
• "Compare X and Y" where the user already has a shortlist and wants analysis (not discovery) </trigger_and_routing>

Stage 1: Interview

Read references/interview-calibration.md before composing questions.

Outcome: A filled interview handoff block (see <handoff_contracts>) with enough signal to rank the masterclass criteria and differentiate tiers. Every question must plausibly change the final shortlist — drop any that won't.

Generate category-specific questions using the frame in that reference. The pipeline already surfaces budget-to-premium tiers for every run, so skip budget unless the user likely has a hard cap that would exclude entire tiers. Fewer, sharper questions beat a longer list with padding.

AskUserQuestion accepts at most 4 questions per call. Batch accordingly; use multiple sequential calls if needed.

Fire a follow-up round only when answers reveal a genuine ambiguity that would lead to a wrong shortlist — e.g., contradictory constraints the user needs to rank, or a critical category-specific variable that wasn't captured. Mild gaps can be filled by preliminary-phase research.

Write full Q&A and the structured handoff block to 01-interview.md with angle-file frontmatter (role: angle, sub_question: "interview").

Stage 2: Preliminary phase — aspect discovery, deep research, and masterclass

Three sub-stages executed sequentially (2a → 2b → 2c). The availability subagent runs in parallel with 2b.

Stage 2a: Aspect Discovery (main context)

Goal: Identify the key dimensions of this product category — broadly, not scoped by interview priorities.

Run 2-3 broad searches in the main context. Do NOT reference the user's stated priorities in these queries — the goal is pure category discovery.

1. research.py ask "what are the most important factors and dimensions to evaluate when buying a [category]? Cover all aspects: performance, build quality, ergonomics, safety, materials, maintenance, durability, accessories" --context high
2. youtube.py search "[category] buying guide what to look for [current year]"
3. research.py ask "[category] common buyer mistakes things people overlook biggest regrets after buying"

From the combined results, compile a list of 8-12 key aspects of the product category. These should be fundamental dimensions that differentiate products — not features of specific models.

Cluster the aspects into 3-4 groups of related dimensions. Each cluster should make sense as a coherent research topic (e.g., for a stroller: {wheels, suspension, terrain handling}, {fold mechanism, weight, portability}, {safety, materials, build quality}, {canopy, storage, accessories, ergonomics}).

Stage 2b: Aspect Deep-Dives + Availability (all subagents in parallel)

Spawn all subagents with subagent_type: "research-subagent". Run 3-4 aspect subagents + 1 availability subagent in parallel.

Aspect deep-dive subagents (3-4)

Each subagent receives the product category and use case context from the interview, but NOT the user's stated priorities — the goal is category education, not priority validation.

Prompt skeleton (per cluster):

You are researching [aspect cluster name] for [category] to build a buying guide that educates a first-time buyer on what truly matters.

Your assigned aspects: [list of 2-3 aspects in this cluster]

For each aspect, research and document:

1. What it is and why it matters — plain-language explanation of the engineering or design dimension
2. What to look for — specific specs, features, or qualities that indicate quality vs. cost-cutting
3. What to avoid — red flags, misleading specs, marketing traps specific to this aspect
4. Real-world owner experience — things people discover only after purchase (from Reddit, forums, YouTube long-form owner reviews)
5. Engineering tradeoffs — where improving this aspect necessarily compromises another aspect (e.g., bigger wheels = harder fold)

Use research.py ask, social.py reddit, youtube.py search, and research.py scrape as needed. Aim for 3-5 quality sources per aspect. Do NOT use --recency flags.

Do NOT rank or score specific products. This is educational research about the ASPECTS themselves, not about models.

Write to aspects/[cluster-slug].md with angle-file frontmatter.

Availability subagent

Goal: Map the retailer universe for this category in RO (first) + EU/import fallback, then identify the best starting platforms. Do not narrow discovery to 3-4 platforms too early.

Prompt skeleton:

Build a retailer universe for buying [category] with delivery to Romania. Start with Romanian retailers, but do not stop at eMAG/Altex/Flanco. Include:

1. Big-box / marketplace retailers (eMAG, Altex/Media Galaxy, Flanco, Cel.ro, Dedeman, etc.)
2. Official brand stores or official local distributors when relevant (e.g. russellhobbs.ro, shop.tefal.ro, smeg.com.ro)
3. Specialty/category retailers (e.g. etbm.ro for lights, avstore for audio, coffeegear.ro for coffee, KitchenShop/Conox-type kitchen specialty stores)
4. Romanian price/discovery aggregators (Compari.ro, Price.ro, Pricy.ro/PriceFlux-like pages when available) as discovery surfaces for additional seller domains
5. EU retailers shipping to RO (Amazon DE, Bol.nl, category-specific EU specialty) when Romanian coverage is thin or a globally strong model is unavailable domestically

Produce two sections:

1. retailer_universe: all valid seller/discovery domains found, grouped by seller type. For each: name, base/category URL, seller type, strength, caveats, and whether it should be used as primary, secondary, or verify-only.
2. availability_shortlist: the 3-6 best starting platforms for Stage 3, chosen from the universe. This shortlist is a starting point, not a boundary; Stage 3 must still run model-level deal sweeps across the wider web.

Add a market_depth_judgment: broad, moderate, or thin, with a short rationale. Use human judgment: if many Romanian sellers/categories are clearly present, keep the universe broad; if the category is genuinely sparse, document the dead ends and make import options explicit.

Write to 03-availability.md with angle-file frontmatter.

Wait for all subagents to complete. Check that all aspect files in aspects/ and 03-availability.md exist and have expected content.

Stage 2c: Masterclass Assembly (main context)

Read references/masterclass-template.md before writing.

Read all aspect deep-dive files from aspects/. Compose 02-masterclass.md following the masterclass template structure:

• Organize by aspect cluster (educational structure, not priority order)
• Each aspect: what it is, what to look for, what to avoid, real-world gotchas, key tradeoffs
• Conclude with three sections:
  • Ranked criteria (5-10 items) — personalized to the user's use case using interview context. The interview priorities influence the RANKING of criteria, not the COVERAGE of aspects.
  • Marketing myths (2-5 items) — consolidated from aspect research, with source basis
  • Decision framework — practical guidance for the user's specific situation

Extract the ranked criteria and marketing myths into the handoff block for Stage 3. If aspect research reveals contradictions with the user's stated priorities (2+ independent sources), note them in the masterclass and carry them forward to the synthesis.

Stage 3: Product phase — 3 subagents in parallel

Each subagent receives: full interview handoff + ranked_criteria + myths_to_ignore + retailer_universe + availability_shortlist + market_depth_judgment. Spawn all three in parallel with subagent_type: "research-subagent".

Owner voice subagent

Goal: Real-world ownership signal.

Prompt skeleton:

Find owner perspectives on [category] from Reddit long-form (r/BuyItForLife, r/[category], category-specific subs) and non-affiliate YouTube reviewers. Use social.py reddit and youtube.py search.

Focus on: multi-year reliability, quirks not mentioned in expert reviews, deal-breakers that only surface with real use. Score candidates against the ranked criteria provided.

Produce 5-8 candidate models with owner-voice summary per model (what owners love, what fails, deal-breakers).

Write to 04-owner-voice.md.

Expert voice subagent

Goal: Comparative analysis against the ranked criteria.

Prompt skeleton:

Compare top models in [category] using expert/trade sources. Use research.py ask with context=high, research.py reason for comparative analysis, and research.py scrape for 2-3 trusted expert/trade source pages.

Avoid affiliate/SEO sites (generic "best of" roundups). Prefer named expert reviewers, trade publications, and specialized review sites.

Score candidates against the ranked criteria. Produce 5-8 candidates with comparative notes per model and explicit criteria scoring.

Write to 05-expert-voice.md.

Retailer voice subagent

Goal: Current availability, pricing, and best reputable deal for candidate models.

Prompt skeleton:

For [category], identify 5-8 candidate models via WebSearch (owner/expert subagents run in parallel — do not read their outputs). Use the availability shortlist as a starting point, but use the wider retailer_universe and model-level web searches to avoid overindexing on eMAG/Altex/Flanco.

For each candidate/model family, run a model-level deal sweep before concluding availability:

• Search exact model number/name + Romanian buying terms: "<model>" pret Romania, "<model>" site:.ro, "<model>" [Romanian category term], and "<model>" compari.ro OR price.ro OR pricy.ro.
• Check official brand/local distributor stores when the brand has a Romanian presence.
• Use aggregators as discovery surfaces: follow seller domains they reveal; do not cite only the aggregator when a seller page can be found.
• Run research.py scrape or WebFetch on product pages where possible. If a site blocks scraping, record the dead end and use search-result snippets only as lower-confidence evidence.

Per candidate: availability per seller (in stock / out / not listed / unverified), current price (RON or EUR), seller type, warranty/returns if visible, delivery window if visible, and the best reputable deal found.

Add a coverage_judgment section. Use human judgment, not a hard seller count:

• If the category/model clearly appears across many Romanian sites, keep expanding beyond the shortlist until the main seller classes are represented and the best deal is plausibly found.
• If the category/model is genuinely limited, say which searches/sites were tried, why coverage appears thin, and whether EU/UK/US import options should be considered.
• Do not claim "only X options exist" unless broad searches, aggregators, official stores, and specialty sellers were checked or attempted.

Write to 06-retailer-voice.md.

Stage 4: Verification

After all three product-phase subagents return, orchestrator identifies the 6 final recommendations (3 tiers × primary + runner-up). For each:

1. Scrape the primary retailer URL via research.py scrape <url> (no --recency flag).
2. Check for:
   • Out-of-stock signals: "out of stock", "discontinued", "not available", "indisponibil", "stoc epuizat", 404, redirect to category page
   • Current price
   • Title match (did we land on the right product?)
3. Tag each recommendation:
   • verification: verified (default; omit from output to reduce noise)
   • verification: manual — link didn't confirm availability (scrape ambiguous or failed)
   • price-changed: was X, now Y (>20% price delta from research-captured value)

Do not rewrite recommendations based on verification results. Flag only. The recommendation reflects quality; the flag reflects current stock state.

Stage 5: Synthesis

Read references/synthesis-template.md before writing.

Write 00-synthesis.md following the exact structure. Key reminders:

• Master class section is a condensed summary (400-800 words) of the full masterclass document (02-masterclass.md), with a link to it. Include ranked criteria highlights and key myths. Omit the "what we learned vs your initial assumptions" subsection entirely if no contradictions cleared the 2-source threshold.
• Market reality line is standard; include for every run.
• 3 tiers by default (overall / budget / premium). Substitute tier name with use-case axis if default doesn't fit the category. Omit a tier entirely if no strong candidate exists.
• Considered-and-discarded section: 2-3 items from (1) shortlist fallout, (2) SEO-popular but expert-rejected. Each MUST cite specific source/finding. Do not pad.
• Confidence tag per recommendation with a one-line reason.
• Verification flags go on "Where to buy" line, not on the recommendation itself.

Prepend a run entry to ~/Documents/Research/INDEX.md following the format in ../research/references/persistence-format.md.

<handoff_contracts>

Interview → Preliminary

Adaptive YAML. category and stated_priorities are required. Others optional:

category: <product category>
use_case: <free-form summary>
stated_priorities: [ordered list, top 2-3]
stated_dealbreakers: [list]
budget_signal:
  type: fixed | range | flexible | none_given
  value: <if applicable>
constraints: [space/physical/environmental notes captured]
experience: first-time | replacing-known | upgrading | not-asked
raw_qa: [full Q&A for exact phrasing reference]

Preliminary → Product phase

Ranked criteria and myths are extracted from the masterclass (Stage 2c). Retailer data comes from the availability subagent. Adds the following on top of the interview block:

ranked_criteria:
  - criterion: <name>
    why_it_matters: <1 sentence>
myths_to_ignore:
  - myth: <name>
    source_basis: <short note>
contradictions_with_user_priorities:
  - user_priority: <what user said>
    research_finding: <counter-signal>
    sources: [url1, url2]
retailer_universe:
  - platform: <name>
    url: <base/category URL>
    seller_type: big_box | marketplace | official_brand_store | specialty | aggregator | eu_import | other
    use_as: primary | secondary | verify_only
    strength: <short note for this category>
    caveats: <optional>
availability_shortlist:
  - platform: <name>
    url: <base/category URL>
    strength: <short note for this category>
    caveats: <optional>
market_depth_judgment:
  level: broad | moderate | thin
  rationale: <why the market appears broad/moderate/thin and what import fallback, if any, should be considered>

Product phase → Synthesis

No separate contract. Orchestrator reads 04-owner-voice.md, 05-expert-voice.md, 06-retailer-voice.md and composes the synthesis.

</handoff_contracts>

<edge_cases>

• Thin aspect research (sparse sources for obscure category) → masterclass assembly works with best available data; flag lower confidence in synthesis and note which aspects had thin coverage
• Masterclass fails to produce ranked criteria → fall back to user priorities for Stage 3 scoring rubric; note the fallback in synthesis
• Unrealistic budget (user says 1500, market starts at 3000) → no explicit warning; the market-reality line in synthesis does the educating naturally
• Tier with no strong candidate → substitute tier name with use-case axis (e.g., "best for small spaces"), or omit tier entirely. Never invent.
• Thin retailer market → document searched retailer classes and dead ends, then consider EU/UK/US import options as Yellow/Red availability rather than forcing a domestic recommendation
• Whole category is US-only → flag in synthesis that no EU-available options exist at meaningful tiers; still produce what's available
• Verification fails for a recommendation → tag verification: manual, keep recommendation in the output
• User's stated priorities fully align with research → omit "what we learned vs your initial assumptions" subsection; don't pad
• User named specific models in interview → ensure product-phase subagents evaluate those models. If they don't make the shortlist, address them in the considered-and-discarded section regardless of the 2-item minimum. </edge_cases>

<anti_patterns>

• Do NOT surface single-source contradictions in the master class. Only 2+ independent quality sources trigger the "what we learned" subsection.
• Do NOT pad the considered-and-discarded section to hit 3 items. One well-justified discard beats three padded.
• Do NOT write "no contradictions found" or "no myths to note" filler. Omit those subsections entirely when empty.
• Do NOT use a generic interview question list. Generate per-category questions using the interview-calibration frame.
• Do NOT treat eMAG/Altex/Flanco as the whole Romanian market. They are starting points, not boundaries.
• Do NOT claim a model/category has only a few Romanian options unless broad web search, official brand stores, specialty sellers, and price aggregators were checked or attempted. </anti_patterns>

<reference_index> Lazy-loaded during specific stages:

• references/interview-calibration.md — load at Stage 1 (Interview) before composing questions. Contains the question-generation frame and 3 calibration examples (microwave, mattress, vacuum).
• references/masterclass-template.md — load at Stage 2c (Masterclass Assembly) before writing 02-masterclass.md. Contains the document structure, voice guidelines, and length targets.
• references/synthesis-template.md — load at Stage 5 (Synthesis) before writing 00-synthesis.md. Contains the exact output structure and a worked example.

Cross-references to the research skill (same project):

• ../research/references/cli-reference.md — CLI invocations for research.py, youtube.py, social.py
• ../research/references/persistence-format.md — angle-file frontmatter, run directory conventions, INDEX.md format </reference_index>

<success_criteria> Ordered by skip risk (highest first).

• Pipeline runs all 5 stages in order. Preliminary (Stage 2) — including aspect discovery (2a), deep-dives (2b), and masterclass assembly (2c) — completed before Product phase (Stage 3) spawned.
• Interview questions generated per-category using the interview-calibration frame, not from a generic template.
• Aspect discovery searches are category-generic, not scoped by interview priorities.
• Masterclass document (02-masterclass.md) covers all discovered aspects with educational depth, not just user-priority-aligned criteria.
• Ranked criteria (extracted from masterclass, not raw user priorities) used to score and order candidates in product phase.
• Availability phase produces a retailer universe plus a shortlist; the shortlist is not treated as an exclusive boundary.
• Retailer voice performs model-level deal sweeps for finalists/candidates, including official brand stores, specialty sellers, and Romanian price aggregators when available.
• "What we learned vs your initial assumptions" subsection appears ONLY when 2+ quality sources contradict a user priority; omitted entirely otherwise.
• Synthesis follows synthesis-template.md structure: master class + market reality line + 3 tiers × (primary + runner-up) + tradeoffs + considered-and-discarded.
• Verification flags ambiguous recommendations with verification: manual — never rewrites them.
• Run persisted to ~/Documents/Research/<slug>/ with slug YYYY-MM-DD-<category>-product-research — 00-synthesis.md + 01-interview.md + 02-masterclass.md + 03-availability.md + 04-06 voice files + aspects/*.md; INDEX.md updated with a single run entry.
• No --recency flags used on any CLI call during the run. </success_criteria>