elimination-research

Elimination Research

Purpose

Generate a reproducible elimination-research package: a shortlist dataset, numeric scoring model, quick consumer report, full audit report, raw data JSON, source/domain audit, purchase/info links, contextual images, and ownership-cost estimates.

Use this skill to turn fuzzy "which one should I choose?" requests into a clean decision workflow with explicit criteria and inspectable data.

Workflow

Follow this sequence for new comparisons:

1. Read references/workflow.md for the full operating procedure.
2. Ask the intake questions before researching. Prefer cenno popup questions when available. Use closed choices and include a free-text comment field.
3. Gather candidate, source, price, spec, replacement-part, image, and evidence data.
4. Save all collected data into a dataset JSON matching references/dataset-schema.md.
5. Run scripts/generate_elimination_report.py to generate reports.
6. Verify the quick report and full report in a browser.
7. Preserve raw data and numeric tables; do not hide or discard evidence just because the quick report is simplified.

Intake Questions

Ask these at the start of a new comparison, not inside the final report:

• What matters most: overall quality, lowest price, sensitive-skin/user-fit, low maintenance, or travel/portability?
• What is the hard limit: budget ceiling, must-have features, excluded brands, or purchase country?
• How much evidence is needed: quick consumer view, full audit report, or both?
• Which source types are allowed: manufacturer, retailer, price aggregator, expert review, forum, or all with flags?

Always include a comment field for constraints that do not fit the closed choices.

Output Contract

Produce these files in the chosen output directory:

• quick_report.html — consumer-facing "don't make me think" report with cards/table switch, images in context, rounded prices, links, and visible ownership summaries.
• report.html — full audit report with task, criteria, scoring, raw numeric data, source/domain tables, tournament, and embedded JSON.
• report.md — markdown version of the full audit report.
• final_report.json — normalized report payload.
• raw_research_data.json — collected dataset before rendering.
• image_search_results.json — cached Google image-search output when image refresh is used.

The quick report should keep numeric detail behind expandable evidence links, but the full report must expose all numeric data as tables.

Generator

Run the bundled generator from the skill directory:

python3 scripts/generate_elimination_report.py \
  --dataset assets/examples/consumer_goods_dataset.example.json \
  --output-dir /tmp/elimination-report \
  --max-price-eur 200

Common options:

--dataset PATH             Structured shortlist dataset JSON
--output-dir PATH          Output directory
--max-price-eur NUMBER     Purchase-price ceiling override
--price-limit-basis FIELD  Usually device_price_eur or three_year_cost_eur
--question TEXT            Override report task question
--market TEXT              Purchase market/country
--currency TEXT            Currency label
--domain-registry PATH     Optional domain registry JSON
--refresh-images           Refresh Google Custom Search image data
--image-results NUMBER     Image results per candidate when refreshing

For Google Images, load keys only from environment variables or SOPS-encrypted dotenv files. Never commit plaintext keys. The image helper checks GOOGLE_CUSTOM_SEARCH_JSON_API_KEY, GOOGLE_CUSTOM_SEARCH_API_KEY, GOOGLE_CUSTOM_SEARCH_CX, and GOOGLE_IMAGE_SEARCH_ENV_FILE.

Data Rules

Read references/dataset-schema.md before creating or editing the dataset.

Key requirements:

• Use stable candidate IDs.
• Keep every numeric observation as a number, not prose.
• Store prices in explicit currency fields such as device_price_eur.
• For replaceable parts, include rough replacement_unit_price_eur, replacement_quantity_3y, replacement_interval_months, and replacement_part_name.
• Include item_links or source references so each item has 1-3 purchase/info links.
• Classify source domains by role and trust tier. Manufacturer/spec, retailer, price aggregator, expert review, forum, and affiliate sources should remain distinct.
• Store caveats explicitly. Do not silently remove weak assumptions.

Report Design Rules

For consumer reports:

• Let product images illustrate the options in context; do not create a standalone image-source section.
• Keep image blocks on a light neutral background.
• Hide image host/score/dimensions from the consumer report; keep them in JSON.
• Round visible prices in the quick report.
• Avoid eyebrow labels.
• Provide a card/table switch where cards and table are mutually exclusive views.
• Show ownership cost directly on each option card/table row when replaceable parts exist.
• Keep source links as short action chips: price, official, review, parts, or head price.

For audit reports:

• Start with the task and criteria so the report is understandable without conversation context.
• Show all numeric data as tables.
• Include the full candidate dataset, domain/source audit, score formula, tournament rows, sensitivity rankings, and caveats.

Verification

Before handing off:

• Run the generator on the dataset.
• Validate JSON with python3 -m json.tool.
• Open quick_report.html and verify the card/table switch replaces the options view rather than stacking table below cards.
• Check mobile width for text overflow, low contrast, and touch targets under 44px.
• Confirm report.html includes raw numeric columns for device price, replacement allowance, part unit price, interval, quantity, and three-year cost.
• Commit and push changes when editing the skills repo or generated report project.