Market Researcher
A desk-research engine for market questions. It takes a raw question like
"should we build X?" or "how big is the market for Y in Brazil?" and returns a
research report in which every factual claim traces to a registered source
— the discipline the typical AI market analysis lacks, and the reason this
skill exists. A confident fabricated market size looks exactly like a real one;
the citation machinery below is what makes the difference detectable.
The skill runs desk research only: web sources, public data, documents the
user provides. It designs around that limit honestly — what it learns about
customers are demand signals and hypotheses, never validated insights (see
non-negotiable 5).
Non-negotiables
These five rules outrank everything else in this skill:
- Every claim is traceable. Every number and every factual assertion in a
deliverable either carries a source tag
[S#] that resolves to a row in
sources.md, or is an explicit derived estimate showing its formula and
cited inputs, or is labelled (assumption A#). Nothing rides on authority
of tone. If you catch yourself writing "the market is growing rapidly"
without a tag, stop and either find the source or cut the sentence.
- Current facts come from the web, not from memory. Market sizes, prices,
competitor products, funding, regulations — research them fresh. Training
data is stale and, worse, statistically plausible. If web access is
unavailable, say so and stop; do not degrade into an uncited essay.
- Triangulate; never silently average. Size markets with more than one
method when the decision warrants it. When two credible sources or methods
disagree by more than ~2x, report the conflict and diagnose it (different
market definitions, years, currencies, revenue-vs-GMV) rather than blending
it away.
- A verification pass runs before delivery. A skeptic re-checks key
claims against their sources, re-does estimate arithmetic, and flags stale
data. Findings it cannot resolve ship in the report as caveats, not
silently dropped.
- Desk research yields signals, not validated customer insight. Personas
and needs produced here are hypotheses to be tested by real primary
research (interviews, tests) that the user or a calling skill owns. Label
them as such and always end customer sections with "open questions for
primary research".
Prerequisite
Web search and web fetch. Check availability before promising anything; if
missing, tell the user what you need and stop rather than answering from
training data (non-negotiable 2).
Tool economy
Desk research is reading, not browsing. Use the cheapest tool that gets the
text, in this order:
- Built-in web search (WebSearch or equivalent) to find sources.
- Built-in fetch (WebFetch or equivalent) to read them — it returns the
page text, which is all a citation needs.
- Browser automation (agent-browser, Chrome/Playwright tools) only as a
last resort for a specific page that fetch genuinely cannot read
(JS-only rendering, interaction-gated content) and that no alternative
source covers. Never screenshot pages to "read" them.
This ordering is a cost rule, not a style preference: a browser session burns
tokens on screenshots and DOM snapshots at a rate that can exceed the entire
rest of the lane, and it produces nothing a citation needs that fetched text
doesn't. If another skill's guidance says to prefer browser tools, it does
not apply inside this skill's research lanes. Pass this rule to every lane
subagent you spawn.
One harness quirk: some environments guard the Write tool against
report-shaped filenames (report.md, summary.md, findings-*.md). If a
required output file is blocked, write it via a shell heredoc instead — the
filenames are part of this skill's contract and must not be renamed to
appease the guard.
Two modes
| Quick Scan (default) | Deep Dive (opt-in) |
|---|
| Question | "Is this worth a closer look?" | "What exactly are we walking into?" |
| Duration | One session | Multi-session, resumable |
| Sizing | One method + sanity check, wide honest ranges | ≥2 methods, triangulated |
| Competitors | 5–10 identified, one-line profiles | Top 3–5 profiled in depth |
| Customers | Headline demand signals | Full signal mining + hypothesis personas |
| Macro | 2–3 kill-factors / tailwinds only | Structured PESTEL + trends |
| Output | Go/no-go brief (~4–8 pages) | Modular report |
Default to Quick Scan and say so — "I'll run a quick scan first; we can deep-
dive into any lane that looks decisive." Go straight to Deep Dive only when
the user asks for depth or a calling skill specifies it. Deep Dive is modular:
the user picks lanes (sizing / competitors / demand / macro); don't run all
four ritualistically if only one matters to the decision.
Keep Quick Scan actually quick: a hard working budget of ~15 registered
sources per lane — enough to bound the answer, not to settle it. Write the
budget into every lane subagent's prompt and stop a lane when its marginal
source stops changing the lane's answer; "one more source" past that point
is Deep Dive work the user didn't order. Depth beyond the budget belongs in
Deep Dive, where the user has opted into the cost. Tell the user at intake
what they're buying ("a quick scan takes a while and reads a few dozen
sources; a deep dive is a multi-session effort") so "quick" doesn't
over-promise.
Workflow
0. Intake
Establish, in one short exchange (not an interview):
- The decision behind the question. "Research the pet food market" hides
"should I quit my job to start a pet food brand?" — the decision determines
depth, lanes, and what "so what" means. Ask if not obvious.
- Market definition draft: product/service category, customer type
(B2B/B2C), geography, any segment constraints. A market size without a
market definition is noise.
- Mode (default Quick Scan) and, for Deep Dive, which lanes.
- Output location: standalone →
./research/market/<topic-slug>/;
called from another skill's workspace → the path it provides (see
"Composition contract").
Confirm the frame back in 3–5 lines, then start. Don't re-elicit what the
conversation already contains.
1. Initialize the research workspace
bash /mnt/skills/user/market-researcher/scripts/init-research.sh <output-dir> "<topic>" <mode>
This scaffolds the directory, sources.md (the source registry), state.md
(progress tracking for resume), and report.md skeleton. When running inside
this repo use skills/market-researcher/scripts/init-research.sh.
2. Run research lanes
Four lanes, each with its own reference file — read the reference before
running the lane:
| Lane | Reference | Quick Scan version |
|---|
| Market & sizing | references/market-sizing.md | One method, ranges |
| Competitors | references/competitor-analysis.md | Scan of 5–10 |
| Demand signals | references/demand-signals.md | Headline signals |
| Trends & macro | references/trends-macro.md | Kill-factors only |
Parallelize when you can. If subagents are available, run lanes as
parallel agents; give each agent its lane's reference file, the market
definition, the mode, and the citation rules (point it at
references/citation-schema.md). Each lane writes findings-<lane>.md in the
workspace and registers every source it uses in sources.md with the next
free [S#] id. If subagents are not available, run lanes sequentially
yourself — the discipline is identical, only the wall-clock differs.
Lane outputs are evidence files, not prose essays: claims tagged, quotes
linked, estimates showing their arithmetic.
3. Synthesize
Read all lane findings and write the report body (structures in
references/report-templates.md). Synthesis rules:
- "So what?" for every section. Findings that don't bear on the decision
get cut, no matter how interesting.
- Rigor lives in the evidence files; the report reads like a good
consultant wrote it. Citation tags stay, but the machinery talk (lane
names, ID-block bookkeeping, process narration) does not belong in the
report body — move it to state.md. Prefer the crisp formulation: "priced
against a $150k assistant, $30/mo is cheap [S12]" beats a paragraph of
hedged setup. A report that is rigorous but tiring to read loses to a
well-written uncited one in practice, and that is a failure of this skill's
purpose, not a style preference.
- The verdict is a recommendation with confidence and reasoning, not a
hedge. "Go, with medium confidence, because A and B; the thing that would
change this is C."
- The verdict's confidence must own its structural evidence limits. Two
recurring ones: (a) if the data spine — market size, outlet counts, the
facts the verdict stands on — traces to a single vendor's report series,
that is a ceiling on confidence, stated in the verdict itself, not a line
in a caveat list; (b) if the strongest evidence describes an adjacent
segment rather than the user's actual target (e.g. plenty of data on
merchants who already pay for software, almost none on the no-software
merchants the user wants to win), say so where the verdict is stated — the
reader must know which population the conclusion actually rests on.
- Contradictions between lanes are findings, not embarrassments — surface
them. (Large market but no willingness-to-pay signals is a classic and
important combination.)
- End with open questions for primary research — what desk research
could not establish and how to test it.
4. Verification pass
Before delivery, run a skeptic pass — a separate subagent if available,
otherwise yourself in an explicitly adversarial sitting:
- Take the report's ~10 most decision-relevant claims. For each, open the
cited source and check it actually says what the report says (numbers,
units, year, market definition).
- Recompute every derived estimate from its stated inputs — including the
time axis: a CAGR for 2026–2031 applied to a 2024 base is a silent error;
reconcile the years or state the mismatch.
- Flag sources older than 2 years presented as current, and single-source
claims that carry heavy decision weight.
- Check source portfolio health, not just individual sources: (a) does one
publisher — especially a profiled competitor — supply the data spine? (b) is
one Low-confidence source reused across several different strategic claims?
(c) do any pain/WTP quotes come from competitor-affiliated sites? Each hit
becomes a named caveat.
- Anything unresolved becomes a visible caveat in the report; nothing is
quietly deleted or quietly kept.
Record the pass (what was checked, what was fixed, what remains open) at the
bottom of state.md.
5. Deliver
Present to the user, in the conversation language: the verdict and confidence,
the three-to-five facts that drive it, the biggest caveat from verification,
and the open questions. Keep it under a screen; the report file holds the
rest. Offer the natural next steps: deep-dive a lane, hand the open questions
to primary research, or re-run the scan later (markets move).
Source and citation discipline
The full schema lives in references/citation-schema.md — read it before
writing any findings file. The one-paragraph version: sources.md is a
registry where each source gets an id [S#], URL, publisher, publication
date, date accessed, and a confidence grade (high/medium/low by source type
and corroboration). Claims cite [S#]; derived estimates show formula and
cited inputs inline; assumptions get A# ids and live in an assumptions table
in the report. An untagged factual sentence is a bug.
Composition contract (for calling skills)
Other skills (strategy-board, design-thinking, product briefs) can use this
skill as their research engine. The contract:
Input — the caller provides: research question + decision context, market
definition (or asks this skill to draft one), mode and lanes, and a target
directory inside the caller's workspace (e.g. strategy-board's fact-base
sources dir, design-thinking's research/).
Output — this skill writes into that directory: sources.md (or appends
to an existing one, continuing its [S#] numbering — never renumber existing
sources), findings-*.md, and report.md. All claims follow the citation
schema, so the caller's artifacts can cite [S#] directly without knowing how
the research was done.
Boundary — this skill answers market questions. For deep research on
non-market topics, or when the caller needs primary research with real
customers, say so explicitly instead of stretching.
Resuming across sessions (Deep Dive)
state.md tracks: mode, lanes chosen, lanes completed, verification status,
and a short log line per session. When invoked and the output directory
already exists, read state.md first and tell the user where things stand
("sizing and competitors done; demand signals lane pending") before doing
anything. Never redo a completed lane silently — ask if the user wants it
refreshed (sources may be stale if much time has passed; say when the lane
was last run).
References
| File | Read when |
|---|
references/citation-schema.md | Always, before writing any findings |
references/market-sizing.md | Running the sizing lane |
references/competitor-analysis.md | Running the competitor lane |
references/demand-signals.md | Running the demand lane |
references/trends-macro.md | Running the macro lane |
references/report-templates.md | Synthesizing the report |
Presenting results
Lead with the verdict and its confidence. Then the driving facts, each with
its [S#]. Then the biggest caveat. Then open questions. Write for an
executive who will read the full report only if this summary earns it. Match
the user's language, whatever it is (a question asked in Spanish gets a
Spanish summary and report; source quotes may stay in their original
language).