Ingredient Opportunity Research

An evidence-led AI research skill for ingredient and raw-material teams: turn fragmented market information into an auditable feasibility report and downstream customer-development actions before committing to process development, capacity build-out, or market entry.

Status (v1.2): v1 shipped; currently in cross-ingredient validation and maintenance. The core deliverable is a decision chain, not a report: evidence ledger → executable validation checklist → expert decision.

Full Chinese narrative (product thinking, case audits, iteration history): docs/README.zh.md · Product requirements (spec, metrics, non-goals): docs/PRD.md · Design decisions: docs/product-case-study.md · Change log: CHANGELOG.md

Contributing / before pushing: structural checks, the report-format contract and tests run automatically before every push (.githooks/pre-push) and again in GitHub Actions on push. First clone: git config core.hooksPath .githooks. Live-link checking is a separate local tool — python3 scripts/check_links.py — kept out of CI because external sites rate-limit or go down (it flags definitive 404/410 as dead; 403/429 and timeouts are reported as warnings, and RFC 2606 placeholder domains are skipped).

Who it's for

• Primary: strategy and market-research teams at chemical companies who must decide — before process development or capacity investment — whether a new ingredient is worth pursuing, what the veto gates are, and what must be validated first.
• Also: owners, business and sales leads at companies without a full strategy department, who run opportunity research alongside their day job and need a cross-disciplinary baseline.
• Supporting roles: process R&D, application R&D, sales, regulatory, finance and industry experts — the system gives them a shared, auditable evidence trail and hands final sign-off back to humans.

Why this exists

A new ingredient can require years of process development and heavy capital before the first tonne sells; if the demand is not there, the company carries the sunk cost. Strategy teams must decide on fragmented public information spanning chemistry, regulation, applications, pricing and customers — and generic AI tends to collapse those mixed evidence layers into a fluent but unauditable "opportunity". This project reverses that sequence: lock the exact identity, trace every application to a measured property, run veto gates, verify adoption at SKU level, and stop with an evidence ledger and validation checklist instead of a confident narrative.

Full background, problem analysis and user context: docs/PRD.md · design decisions and trade-offs: docs/product-case-study.md

What it does

• locks the exact ingredient identity (name, grade, source, strain, jurisdiction) and separates it from similarly named substances;
• traces every proposed application back to a measured property or labels it a hypothesis — never starts from a category list and retrofits benefits;
• applies hard gates (need, regulation, technical fit, use amount, use cost, buyer visibility) before any application advances;
• audits China, the United States and the European Union as separate columns for food ingredients, preserving category-specific use levels;
• maps applications to concrete saleable product formats — "bakery", "beverage" or "soothing skincare" is not a format;
• verifies current adoption at SKU level (current label/ingredient list/filing) and keeps adoption status separate from buyer qualification;
• separates price signals (transactions, quotations, shipment estimates, public listings), ingredient cost from manufacturing cost, and legal permission from demonstrated effect;
• runs a supply–demand gap audit whenever an opportunity claim depends on shortage or undersupply;
• forbids a model-authored opportunity grade; outputs not reliably estimable instead of false precision;
• ends with evidence gaps, the smallest next validation experiments, and decisions reserved for industry experts.

Evidence discipline

Every material claim carries an evidence level (E1–E5) and an inline, retrievable source. The level describes the evidence, not how attractive the opportunity is. Supplier marketing, patents, reviews and company statements are labeled as interested evidence; sales, ratings and continued listing never prove ingredient causality. If the required comparison cannot be aligned, the report says so.

Install

Cloning this repository alone does not expose the skill in every project, but the repo ships a discovery copy at .agents/skills/ingredient-opportunity-research/ — so if you work inside this repo with Codex, Kimi Code, or DeepSeek Harness, the skill is auto-discovered with zero install. To use it in other projects, install it globally:

Quickstart after cloning

git clone <this-repo>
cd ingredient-opportunity-research
# Inside this repo: already usable (auto-discovered from .agents/skills/).
# For other projects:
./install.sh --codex     # personal Codex install, usable in every project
# or ./install.sh --all       codex + repo-level + claude

Then, in any Codex session (this repo, or any project after a global install), say:

Use the ingredient-opportunity-research skill. Research the market opportunity
for <ingredient> in <geography/application area>. Output a feasibility report
first, then identify <N> evidence-backed potential customers.

Platform install paths

# Manual copy equivalents
cp -R skill/ingredient-opportunity-research ~/.codex/skills/        # Codex personal
cp -R skill/ingredient-opportunity-research .agents/skills/         # repo-level (Codex/Kimi/DSH)
cp -R skill/ingredient-opportunity-research .claude/skills/         # Claude Code
cp -R skill/ingredient-opportunity-research .dsh/skills/            # DeepSeek Harness

Requires the agent to have web research, file and PDF tools; the skill defines the workflow, it does not bundle tools. After install, ask the agent to confirm it loaded references/evidence-and-sources.md before starting — the reference protocols are what make the output evidence-traceable.

Degraded mode (limited or no web/PDF tools)

If the agent lacks web research or PDF access, the workflow still runs but degrades honestly instead of inventing precision:

• uses the public-source fallback in references/evidence-and-sources.md — official product pages, marketplaces, filings, job postings and interviews — instead of paid databases;
• lowers evidence levels (E3–E5, or 已验证→推断→待验证) and labels gaps as not reliably estimable;
• lists exactly what could not be verified, so the reader knows which conclusions to distrust;
• never fabricates a source, price, quote, or SKU to fill a gap.

Usage

Invoke it by describing the task; the model matches the skill from its description. You can also name it explicitly.

Use the ingredient-opportunity-research skill. Research the market opportunity
for <ingredient> in <geography/application area>. Output a feasibility report
first, then identify <N> evidence-backed potential customers.

The default output is a Markdown feasibility report. Customer lists, interview guides, key-account cards and presentation outlines are produced only on request, after the report exists. Languages: Chinese, English, or bilingual. More reproducible requests: prompts/example-prompts.md.

What you ask decides what you get — and what is optional

Rules:

• Just an ingredient name ("HMO") defaults to the full market-opportunity analysis; missing details become labeled assumptions, and the report closes with what input would narrow it.
• A general request produces the report only — customer lists, KA cards and artifacts are never auto-added.
• A scoped request produces that piece only, built from the existing report's evidence; it does not re-run the market research.
• No report yet, scoped request → the skill says the piece cannot be evidence-backed yet and produces the feasibility analysis first.
• Inside the report itself, some modules are also optional: the market-size audit, supply–demand gap audit and market-awareness/education sections appear only when they affect the decision.

Examples

Low scores are a product feature: they tell the user where inference must stop and what to buy, ask or experiment next. Index with versions and dates: examples/README.md.

Evaluation (what the repo proves — and does not)

The repo separates structural checks from effect claims:

Details, protocols, anonymized raw outputs and scores: minimal-prompt-benchmark · three-case-comparison · case-audit · iteration-log.

Honest limitations: benchmark cases are synthetic and designed around known failure modes; blind review was done by the same model family, not by industry experts; group-key mappings were not hash-committed before scoring; a DeepSeek cross-model replication did not reproduce the Skill's overall advantage (96.8 vs 96.6, Direct more stable), so the skill's measured benefit is model-dependent and dimension-specific; and there is no evidence yet of real sales, project-approval or ROI improvement. The strongest supported claim is narrow: in these three synthetic cases on the original model family, a one-sentence request plus the skill produced more complete and more stable decision-framework outputs than direct generation — it did not change the headline investment recommendation, and it did not generalize to an overall mean advantage on DeepSeek.

Validation plan (north star and next gates)

North star: expert-agreed decision-blocker recall — the share of regulatory, technical, identity, market and adoption blockers the system identifies out of an expert-consensus list. A missed veto gate can cost more than all search time saved, so efficiency claims are subordinate to blocker recall and factual accuracy.

Preregistered next-validation gates (from the PRD):

None of these gates is met yet — they are the plan. Expert-trial feedback (reported ~80–90% time saving) is user-reported, not independently measured, and is not claimed here as validated.

Repository structure

.
├── skill/ingredient-opportunity-research/  # the installable skill (SKILL.md + references/)
├── docs/                                   # PRD, product case study, Chinese README
├── examples/                               # five evidence-boundary examples (00–04)
├── evaluation/                             # case audit, iteration log, controlled tests, benchmark
├── prompts/                                # reproducible invocation examples
├── scripts/                                # dependency-free validators and statistics
└── .github/workflows/validate.yml          # CI

Roadmap

• v1.0 (shipped): research contract, property-to-market chain, hard gates, product-format screen, evidence ledger, validation checklist, Markdown report, optional customer actions.
• v1.x (current): cross-ingredient validation — compare system output with real prices, capacity, regulation and customers; ≥5 frozen real cases with an expert gold set; multi-reviewer blind review with timing and revision-volume records; minimal rule fixes per failure type.
• v2: composable strategic-analysis tool — structured input/output contract, enterprise data interfaces, versioned evidence objects; composes with financial, technical, competitive and project-decision skills rather than rebuilding their capabilities.
• v3 (only if demand confirms): opportunity-assessment writing workbench — structured intake, evidence-ledger/checklist/report versioning, expert annotations, decision logs, refresh reminders, permissions and audit.

Platformization is not a goal in itself; the skill remains the lighter product form unless long-term collaboration, permission and data-integration needs are confirmed.

Boundaries

• public sources cannot prove confidential formulas, supplier relationships, contract prices or buying intent;
• a legally permitted ingredient is not proof of a finished-product claim;
• a label proves presence, not dosage, causal efficacy or commercial effect;
• patents and supplier application data are experiment starting points, not production recipes;
• all regulatory, price, SKU and company information must be refreshed before commercial use;
• this project supports expert decisions; it does not replace regulatory, formulation, procurement or business owners;
• it is not a monitoring platform: no real-time tracking, database updates, or CRM writes;
• it does not auto-purchase paid data, bypass access controls, or use unauthorized internal material;
• it does not ship unanonymized internal process, cost, quote or capacity data to external models.

License

MIT — see LICENSE.