---
name: market-research
description: Deep, multi-hop web research engine for the marketing agent. Decomposes a business into research questions, deploys specialized subagents (parallel where the host supports it, sequential otherwise), runs smart iterative searches, triangulates sources, and synthesizes a business-SPECIFIC research brief that feeds knowledge/marketing.md. Use at the start of every engagement, before any strategy, audit, offer, or creative. Triggers: new client intake, "research the market", "find competitors", "find the gap", "who is the customer", "what's working in this niche".
runtime: agent-agnostic (Hermes / Claude Code / Codex). Subagent dispatch is capability-detected.
---

<research_budget>
This is the recon arm of the system. Strategy is only as good as the research under it
(<operating_contract> rule 2 in marketing.md). The job is not "produce a report" — it is to
produce a research brief so specific to THIS business that a competitor could not have
written it about themselves. Generic research produces generic strategy produces a failed
public demo. Depth is the product here. Read this whole file before researching.
</research_budget>

<how_this_connects>
INPUT: the intake brief (product name, website, ICP guess, product picture, goal). If any of
those are missing, get them before researching — you cannot personalize research for an
unknown business.
OUTPUT: the research brief contract in <synthesis>. It feeds directly into
knowledge/marketing.md's <market_research_playbook>, <diagnosis_first>, and <channel_selection>.
Every downstream recommendation will cite this brief, so it must be real, sourced, and sharp.
</how_this_connects>

---

<research_contract>

Non-negotiables. They outrank any individual technique below.

1. PERSONALIZATION OR NOTHING. Every finding ties to this business's product, customer, or
   goal. If a finding would be equally true for any company in the category, it is context,
   not insight — dig until you reach the insight only true for them.
   *Why:* the entire product promise is non-generic advice. Generic research is the root
   cause of generic advice, so the anti-generic fight is won or lost here, first.

2. GROUND EVERY LOAD-BEARING CLAIM IN A SOURCE. Anything that will drive a decision (a
   competitor's price, a customer's top pain, a channel's cost) needs a real source, ideally
   two independent ones (<triangulation>). No source → label it explicitly as an assumption
   to verify, never as fact.
   *Why:* confabulated research feels confident and gets people to spend money on a fiction.
   The cost of a wrong "fact" is the customer's budget and the product's credibility.

3. DEPTH SCALES WITH STAKES. A $97 self-serve buyer gets a focused pass; a business betting
   real ad budget gets the full multi-hop deep dive. Match effort to the decision's weight
   (and the user's tier/budget). See <depth_scaling>.
   *Why:* over-researching a tiny decision wastes the user's time and money; under-researching
   a big one is malpractice.

4. PREFER PRIMARY SOURCES; DISTRUST SLOP. Original sources (the competitor's own site/pricing
   page, the customer's own words in reviews/Reddit, SEC filings, the platform's own ad
   library) outrank aggregators, listicles, and SEO content. Be actively skeptical in
   categories that are heavily SEO-gamed (product "best-of" lists, supplements, anything with
   affiliate incentive) and topics prone to motivated misinformation.
   *Why:* the open web is optimized to rank, not to be true. A research engine that believes
   page-one results inherits page-one's biases.

5. CUSTOMER'S OWN WORDS ARE GOLD. When mining pains and desires, capture VERBATIM language
   from real customers. Do not paraphrase it into marketer-speak.
   *Why:* the customer's exact words carry the emotional charge that converts; they become the
   hooks and ad copy downstream (marketing.md <copywriting>). Paraphrase loses the charge.

</research_contract>

---

<phase_0_load_context>

Confirm you have the intake brief. Minimum to research well:
- Product/brand name and the real, current website (fetch it — do not assume).
- The product itself: what it actually does, for whom, at what price.
- The user's stated goal (leads / sales / launch / scale) — this sets what research matters.
- The user's guess at their ICP (you will validate or correct it with research).
- Economics inputs for the profit lens (knowledge/unit-economics.md): price, rough margin/COGS,
  churn or repeat-purchase rate, current marketing spend. Estimates are fine — label them as
  estimates and refine later; the diagnosis needs at least a first-order read on CAC ceiling and
  breakeven ROAS.

If the website is provided, FETCH IT FIRST. It is the single richest primary source about the
business — their current positioning, offer, proof, and conversion path all live there, and
the audit (<audit_rubric>) depends on it.

</phase_0_load_context>

---

<phase_1_research_plan>

Before searching, decompose the business into a written research plan — the explicit set of
questions that, once answered, fully inform strategy. This mirrors how a senior strategist
scopes a project: questions first, searching second.

The standard question set (adapt to the business and goal):
- WHO exactly is the buyer, in their own words? (validate/replace the ICP guess)
- WHO are the competitors across all three tiers (direct, substitute, do-nothing/DIY)?
- WHAT does each competitor offer, charge, and claim — and where are they weak?
- WHERE is the GAP: under-served, over-charged, or poorly-spoken-to segment?
- WHAT are the customer's top pains and desires, verbatim?
- WHERE is this ICP's attention currently UNDERPRICED (channel/format arbitrage)?
- WHAT formats/angles are working in this niche right now (and going stale)?
- WHAT does the business's own site/funnel look like vs. best-in-class?

Assign each question to a subagent role (<phase_2_dispatch>). Write the plan down; it is the
spec the subagents execute and the checklist for saturation.

*Why a written plan:* it prevents aimless searching, makes parallelization possible, and
gives a clear stop condition (every question answered and triangulated).

</phase_1_research_plan>

---

<phase_2_dispatch>

Deploy specialized subagents to run the plan. Full role specs, missions, and output contracts
are in subagents.md — read it. Dispatch is CAPABILITY-DETECTED so this works across hosts:

- HOST CAN SPAWN PARALLEL SUBAGENTS (Hermes subagents, Claude Code Agent/Task tool, etc.):
  dispatch the relevant roles concurrently, each with its mission + output contract, then
  collect and synthesize. Parallel is strongly preferred — independent research questions have
  no dependency on each other, so running them at once is faster and keeps each worker's
  context focused on one job.
  *Why focused workers:* a single agent juggling competitors + customer pains + channel costs
  dilutes attention and mixes findings. One worker, one question, one clean output.

- HOST CANNOT SPAWN SUBAGENTS (or only one context available): run the roles SEQUENTIALLY
  yourself, one research question at a time, writing each role's output to the brief before
  starting the next. Same rigor, just serial. Never collapse the roles into one mushy search
  session — keep the question boundaries.

- ALWAYS: give each worker (or each sequential pass) the business context it needs and ONLY
  the question it owns. Collect structured outputs, not raw dumps.

The core roles (detailed in subagents.md):
1. Competitor Scout — three-tier competitive map + pricing + weaknesses.
2. Customer-Voice Miner — verbatim pains/desires/objections from reviews, Reddit, forums.
3. Gap & Positioning Analyst — the under-served wedge.
4. Underpriced-Attention Scout — channel/format arbitrage for this exact ICP.
5. Offer & Pricing Intel — market price bands, what's bundled, what guarantees exist.
6. Format & Trend Scout — what creative formats/angles are winning and fatiguing in-niche.
7. Buyer-Journey Mapper — how this ICP actually discovers, evaluates, and decides (stages,
   triggers, friction; B2B buying committee).
8. Proof & Asset Auditor — inventory of existing proof vs the proof hierarchy, unproven claims,
   and a 30-day proof-harvest plan.

Dispatch only the roles the goal needs (<depth_scaling>) — not every engagement needs all six.

</phase_2_dispatch>

---

<smart_search_craft>

How each worker (or you) actually searches. This is the deep-search discipline — adapted from
frontier search-agent design. Obey it; it is the difference between "Googled it" and "researched it."

<query_construction>
- Keep queries SHORT: 1–6 words. Long natural-language queries return worse results.
- Start BROAD (often 1–2 words), see the landscape, THEN narrow with detail. Don't open with
  your most specific query — you'll miss the better framing you didn't know to ask for.
- DECOMPOSE abstract or compound requests into concrete sub-queries. "best marketing channel
  for a premium dog course" is not searchable directly; decompose: "dog training course
  pricing", "reddit reactive dog help", "youtube dog training cpm", etc.
- One distinctive concept per query. Use content nouns (the niche, the product, the proper
  noun), not meta-words ("best", "guide", "overview") that just summon listicles.
- Do NOT fire near-duplicate queries — they return the same results and waste the budget.
  If a query underperforms, change the ANGLE, not just a word.
- Per-ENTITY in comparisons: when comparing/ranking N competitors, research each one
  separately rather than one "X vs Y vs Z" query — you get real per-entity depth instead of a
  single biased comparison post.
- Recency: include the current year or "today" only when freshness matters (pricing, trends,
  ad costs, platform changes). For stable facts, don't — it just adds noise.
</query_construction>

<unrecognized_entity_rule>
If a competitor, product, tool, or format name is unfamiliar, SEARCH it before reasoning about
it. An unfamiliar capitalized name is almost always something real you don't know yet, not
something to infer. Never rank or dismiss a competitor you haven't actually looked up.
*Why:* guessing about a real competitor produces confidently wrong positioning — the worst
kind of research error because it looks authoritative.
</unrecognized_entity_rule>

<fetch_dont_skim>
Search snippets are previews, not sources. For any page that matters — a competitor's pricing
page, a high-signal Reddit thread, a key article — FETCH THE FULL PAGE and read it. The
decision-grade detail is almost never in the snippet.
When the user names a specific URL or site, fetch that exact URL first.
</fetch_dont_skim>

<iterative_retrieval_loop>
Deep research is multi-hop, not one-shot. The loop:
1. Search broad → read the best 2–3 results fully.
2. Extract findings AND the new questions/gaps they reveal.
3. Search again to fill those specific gaps (follow citations, named sources, mentioned
   competitors).
4. Repeat until SATURATION: new searches stop changing the answer, or the same sources keep
   recurring, or the research-plan questions are all answered and triangulated.
5. Stop. Diminishing returns is a real stop condition — don't search forever for marginal
   confirmation. If a question can't be resolved, say so explicitly in the brief.
*Why the loop:* the most valuable finding is usually two or three hops deep — a competitor's
weakness mentioned in a review, that you then verify on their site, that then reveals the gap.
One-shot search never reaches it.
</iterative_retrieval_loop>

<tool_call_scaling>
Scale effort to the question's complexity and the engagement's stakes (<depth_scaling>):
- A single fact (one competitor's price): 1 search.
- A medium question (top pains for an ICP): 3–5 searches + a couple of full fetches.
- A deep question (the full competitive + gap map): 8–15+ searches across the iterative loop.
Use the minimum that actually answers it well — efficiency and depth are both virtues; pick the
budget the decision deserves.
</tool_call_scaling>

</smart_search_craft>

---

<source_quality_and_triangulation>

<source_hierarchy>
Trust, high to low:
1. PRIMARY about the subject: the competitor's own site/pricing/ad-library; the customer's own
   words (reviews, Reddit, Discord, YouTube comments, support threads); platform ad libraries
   (Meta Ad Library, TikTok Creative Center); filings; the business's own analytics if shared.
2. CREDIBLE SECONDARY: reputable trade press, original research/reports, expert practitioners
   with track records.
3. AGGREGATORS / LISTICLES / SEO content: use only to discover primaries to verify; never as
   the final word.
Reject sources that exist to rank or to sell affiliate clicks when the topic is commercial.
</source_hierarchy>

<triangulation>
A claim becomes "research-grade" when two INDEPENDENT sources agree (independent = not citing
each other or the same origin). For load-bearing numbers (price, market size, channel cost),
require triangulation or label the figure a rough estimate. When sources conflict, surface the
conflict and the most credible read — don't silently pick one.
*Why:* a single source can be wrong, outdated, or planted; agreement across independent sources
is the cheapest available proxy for truth.
</triangulation>

<skepticism>
Be appropriately skeptical, not credulous and not cynical:
- Heavily-SEO'd commercial categories (product "best of", supplements, software "alternatives"):
  assume ranking ≠ quality; find primaries.
- Surprising/contrarian claims that drive a big decision: raise the bar, triangulate harder.
- Believe straightforward primary facts (a posted price, a real review) without over-checking.
*Why:* the goal is the truest, most useful picture — over-skepticism stalls, under-skepticism
swallows slop. Calibrate to the stakes.
</skepticism>

</source_quality_and_triangulation>

---

<structured_extraction_loop>

For primary-source pages that carry decision-grade data (the business's own site, each
competitor's site/pricing), don't just read prose — extract STRUCTURED data, then verify it,
then fall back to search only if extraction is thin. This loop is reimplemented from the
company-researcher pattern (validate → extract → fallback → review); it makes the research
auditable instead of vibes-based.

1. VALIDATE THE URL. Confirm the page resolves and is the right entity before extracting
   (avoid researching a parked domain, a competitor's blog instead of their pricing, or the
   wrong "Acme"). For the client's own site, fetch the real current URL.
2. EXTRACT STRUCTURED FIELDS. Pull the specific fields the brief needs as structured data, not
   a summary: offer, price tiers + what's included, headline/positioning, proof shown,
   guarantee, primary CTA, and the lead→payment path. Use a scraping/extraction tool
   (e.g. FireCrawl) where available; otherwise fetch-and-parse manually
   (<fetch_dont_skim>).
3. FALLBACK TO SEARCH. If extraction is insufficient (JS-rendered, gated, sparse), fall back to
   web search to recover the missing fields from secondary sources, and label them as such.
   *Why a fallback:* many real pages don't extract cleanly; a research engine that gives up on
   a thin extract silently drops the most important primary source.
4. HUMAN-REVIEW CHECKPOINT (for DEEP engagements / real budget). Before the brief drives spend,
   present the extracted competitive + offer data to the user for a quick correction pass —
   they often know a competitor or price you'd miss. Track revisions; regenerate until accepted.
   *Why:* a human-in-the-loop correction on the foundational facts is the cheapest insurance
   against a confidently-wrong brief, and it raises the user's trust in everything downstream.

</structured_extraction_loop>

<synthesis>

Collapse all findings into the RESEARCH BRIEF — the single artifact that feeds marketing.md.
It is structured, sourced, and business-specific. Required contents:

1. ICP — validated. The one-sentence ICP from marketing.md <market_research_playbook>, now
   backed by evidence: "[role] who wants [dream outcome] but is blocked by [obstacle] and
   doesn't believe [objection]." Note where research CHANGED the user's initial guess.
2. COMPETITIVE MAP — three tiers, each competitor with offer, price, positioning angle, proof,
   and specific weakness. Cite sources.
3. THE GAP — the under-served/over-charged/poorly-addressed wedge, stated as one positioning
   opportunity. This is the most valuable output; make it sharp.
4. CUSTOMER VOICE — top 5 pains and top 3 desires, VERBATIM, with where they were found. These
   are raw material for hooks and copy.
5. UNDERPRICED ATTENTION — the specific channel/format where this ICP's attention is cheapest
   relative to intent, with the reasoning.
6. WORKING FORMATS — what creative angles/formats are currently winning and which are fatiguing
   in this niche (with examples from ad libraries / top content).
7. SITE/FUNNEL READ — quick primary-source read of the business's own site vs. best-in-class
   (hands off to <audit_rubric> for the full audit).
8. OPEN QUESTIONS / ASSUMPTIONS — anything unresolved, flagged honestly, with what would resolve it.

Each item: specific, sourced, and impossible to have written about a different business. If any
item reads generic, it isn't done — go back to <iterative_retrieval_loop>.

HANDOFF — WRITE `.agents/product-marketing.md`. After the brief is accepted, write its essence
to `.agents/product-marketing.md` in the foundation format the tactical skills expect (see
ARCHITECTURE.md). This is the bridge: every adopted tactical skill (copywriting, cro, ads,
pricing, ...) reads that file first, so writing it once means all of them inherit this deep,
grounded research instead of asking the user shallow intake questions. Include: product + price;
the validated one-sentence ICP; verbatim customer pains/desires/objections; positioning + the
GAP; competitive summary; the underpriced-attention wedge; the current offer + value-equation
read; and the user's goal. Keep it current — update it when research changes.

<example>
  <good>"GAP: every direct competitor sells 'social media management' as a retainer to SMBs
  broadly; none speaks to multi-location dental groups specifically, and three of the top five
  Reddit complaints (sourced) are 'agencies don't understand HIPAA in our content.' The wedge:
  HIPAA-aware content for multi-location dental — under-served AND a trust-driver competitors
  ignore."</good>
  <bad>"GAP: there's room to stand out with better branding and more engagement."
  — Why bad: unsourced, generic, true of every market, drives no decision.</bad>
</example>

</synthesis>

---

<depth_scaling>

Match research depth to tier/goal/stakes:
- LIGHT (self-serve / $97 / quick validation): Phase 1 plan + roles 1–3 (Competitor, Customer
  Voice, Gap), ~light search budget, brief with the essentials. Be honest that it's a focused
  pass.
- STANDARD (active business, real but modest budget): all six roles, full iterative loop on the
  gap and underpriced-attention questions, triangulated brief.
- DEEP ($897 / serious ad spend / launch): all roles, multiple hops per question, ad-library
  pulls, primary-source verification on every load-bearing claim, conflict resolution surfaced.
Tell the user which depth you ran, so the confidence level is legible.

</depth_scaling>

---

<rationalizations_to_block>

Catch yourself taking these shortcuts and refuse them:
- "Page one says X, that's the answer." → Page one is optimized to rank. Find the primary
  (<source_hierarchy>).
- "I basically know this niche, I can skip searching." → The unrecognized-entity and
  research-before-opinion rules still apply; the market changed since training.
- "One good source is enough." → For load-bearing claims, triangulate (<triangulation>).
- "I'll paraphrase the customer complaints to sound cleaner." → No. Verbatim or it's worthless
  (<research_contract> rule 5).
- "The user's in a hurry, I'll give a quick generic market overview." → A generic overview is
  the failure mode the product exists to beat. Run a LIGHT pass properly instead.
- "This finding is interesting, ship it." → Is it specific to THIS business and sourced? If not,
  it's trivia, not the brief.

</rationalizations_to_block>

---

<application_checklist>

Before handing off the research brief:
1. Did I fetch the business's actual website?
2. Is every load-bearing claim sourced (ideally triangulated)?
3. Are customer pains captured VERBATIM, with locations?
4. Is the GAP sharp, specific, and decision-driving?
5. Did I name the underpriced-attention wedge with reasoning?
6. Could any item have been written about a different business? (If yes → not done.)
7. Did I state which depth I ran and flag open questions honestly?
8. Did I run searches with short, decomposed, non-duplicate queries and full-page fetches?

If any answer is "no," fix it before synthesis ships.

</application_checklist>
