outreach-research
Ranks target companies for what the user sells, as a lead list. Use when the user wants to know who to target ("find companies", "find potential clients", "lead generation"). Not for deepening a card
SKILL.mdplugins/mz-biz-outreach/skills/outreach-research/SKILL.md
GitHubOutreach Research Pipeline
Overview
You are an orchestrator that drives a full business outreach intelligence pipeline. You receive an outreach goal and autonomously define strategy, research sources, discover companies, scan reputations, enrich with deep intelligence, score leads, write per-company dossier cards, and produce an executive summary report. Every company gets exactly two permanent files: a .json (machine-readable, progressively enriched) and a .md (human-readable dossier card). No bulk JSON arrays.
When to Use
Discovers prospective companies for an outreach goal and produces a scored lead list with a dossier card per company.
When NOT to use
- The user wants to draft outreach letters or messages, or deepen an existing company card — use
outreach-enrich-company; this skill researches targets, not content. - The user wants competitive analysis of a single named company — use
explainordebug certainty:lowon public sources instead. - The user has not defined an outreach goal or target profile — ask before invoking, or scope it first with
outreach-brief.
Input
$ARGUMENTS— The outreach goal. Examples:"find potential clients for our DevOps consulting in DACH region""SaaS companies in Latin America sector:HR-tech limit:30""find AI startups in Singapore for partnership opportunities"
If empty, ask the user what kind of companies they want to find and why.
Scope Parameter
Extract scope modifiers from $ARGUMENTS, case-insensitive. outreach-research is outbound (company discovery), so scope controls which prospective companies enter the funnel, not which files to scan. Remaining text controls the outreach goal (orthogonal).
sector:<value>— restrict discovery to a specific industry/vertical (e.g.sector:HR-tech,sector:fintech). Default: inferred byoutreach-strategistfrom the goal text.region:<value>— restrict discovery to a geographic market (e.g.region:DACH,region:LATAM). It overrides any geography in the goal text or the brief and is a hard filter: the strategist targets it, the source researcher searches it, and scouts drop companies outside it. Default: inferred byoutreach-strategistfrom the goal text; global if no signal.limit:<N>— maximum companies to carry through the pipeline. Default: 20.brief:<run_name>— seed discovery from anoutreach-briefrun. The strategist is given that run'sbrief.jsonandclimate.json, so the target profile, outreach angles, and scoring weights reflect the captured brief and the local business climate, and the sender voice comes from the brief's voice and goal. Default: none (goal text only).- Default — full-scope strategist-driven discovery using only the goal text when no modifiers are present.
Argument Parsing
Extract from $ARGUMENTS:
- goal — the full description (everything not matching a parameter pattern)
- sector — optional, from
sector:<value>(default: inferred by strategist) - region — optional, from
region:<value>; overrides any geography in the goal text or the brief (default: null, so the strategist infers geography from the goal) - limit — optional, from
limit:<N>(default: 20) - brief — optional, from
brief:<run_name>; resolves to<PROJECT_ROOT>/.mz/outreach/<brief_run>/brief.json+climate.json(default: none)
Directory Structure
Two separate directories are used:
- State —
<PROJECT_ROOT>/.mz/task/<task_name>/state.md. This is the source of truth across phases; never rely on conversation memory. - Outreach data —
<PROJECT_ROOT>/.mz/outreach/<run_name>/(called<RUN_DIR>in phase files) holdsstrategy.json,sources.json, temp_scout/and_enrichment/folders, permanentcompanies/<slug>.json+companies/<slug>.mdpairs,scout_summary.md, and<YYYY_MM_DD>_outreach_<goal_slug>.md.
task_name follows the pattern <YYYY_MM_DD>_outreach_research_<slug>; run_name is <YYYY_MM_DD>_outreach_research_<goal_slug> (same leading-date convention). They are independent: task_name identifies the pipeline invocation, run_name identifies the outreach output bundle.
Constants
- PROJECT_ROOT: resolved once in setup with
echo "${MZ_MEMORY_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; expand<PROJECT_ROOT>to it in every command and agent prompt.
Core Process
Phase Overview
| # | Phase | Agent(s) | Details |
|---|---|---|---|
| 0 | Setup | — | Inline below |
| 1 | Strategy | outreach-strategist |
phases/discovery.md |
| 1.5 | User approval of strategy | — (orchestrator, AskUserQuestion) | Inline below (+ phases/discovery.md §Phase 1.5 for details) |
| 2 | Source Research | outreach-source-researcher |
phases/discovery.md |
| 3 | Scout + Dedup | N x outreach-scout (parallel) |
phases/discovery.md |
| 4 | Scan | N x outreach-scanner (parallel) |
phases/enrichment_and_report.md |
| 5 | Enrich | outreach-enrichment-orchestrator |
phases/enrichment_and_report.md |
| 6 | Score | inline (orchestrator) | phases/enrichment_and_report.md |
| 7 | Write Cards | N x outreach-card-writer (parallel) |
phases/enrichment_and_report.md |
| 8 | Report | outreach-reporter |
phases/enrichment_and_report.md |
Read the relevant phase file when you reach that phase. Do not read both phase files upfront.
Phase 1.5: User Approval of Strategy
This orchestrator (not a subagent) presents this gate. This step is interactive and must not be delegated.
Pre-read: Read <PROJECT_ROOT>/.mz/outreach/<run_name>/strategy.json with the Read tool. Capture the full file contents (target profile, sector/geo scope, candidate-source plan, estimated fan-out cost) into context.
State: write state.md with the artifact path and what_remains: [awaiting approval: strategy gate]; Status stays running.
Surface 1 — emit the plan message. Output the strategy verbatim as a normal markdown chat message. Emit the full verbatim contents of <PROJECT_ROOT>/.mz/outreach/<run_name>/strategy.json — do not substitute a path, summary, or placeholder. Structure:
## Strategy ready for review — outreach-research
```json
<verbatim contents of <PROJECT_ROOT>/.mz/outreach/<run_name>/strategy.json>
```
---
**Approve** → proceed to Phase 2 (source research and company discovery) · **Reject** → mark task aborted, no outreach data generated · reply with feedback to revise
Surface 2 — call AskUserQuestion. A short selector — do not re-embed the strategy in the question body, it lives in the plan message above:
- question:
The strategy above is ready for review. - header:
Strategy - options: Approve — proceed to Phase 2 (source research and company discovery) · Reject — abort the task, no outreach data generated
Response handling:
- Approve → add
- strategy approved: .mz/outreach/<run_name>/strategy.jsonunder## Decisionsinstate.md, remove theawaiting approvalentry fromwhat_remains, setPhase: strategy_approved, and proceed to Phase 2. - Reject → update
<PROJECT_ROOT>/.mz/task/<task_name>/state.mdStatus toaborted_by_userand stop. Do not proceed. - Any other reply (feedback) → re-dispatch
outreach-strategistwith the feedback appended, overwritestrategy.json, return to Surface 1, re-readstrategy.json, and re-emit the entire plan message from scratch with the full new contents — never diff-only, never summary-only, since context compaction may have destroyed the user's memory of earlier iterations. This is a loop — repeat until the user explicitly approves. Never proceed to Phase 2 without explicit approval. - No answer → set
Status: blocked, keepawaiting approval: strategy gate, stop. A missing answer is never approval.
Red Flags
- You dispatched enrichment before the user approved the target profile.
- You used a banned data source (scraped LinkedIn, unverified aggregators, AI-summarized listings).
- Report lives in chat instead of
.mz/reports/or the run's executive summary file.
Verification
Before completing, output a visible block showing: run name, company count after dedup, scored leads count, and the absolute path of the executive summary report. Confirm the report file and per-company card pairs exist on disk.
Phase 0: Setup
Resolve PROJECT_ROOT with the command in Constants, before any cd or worktree switch, and use it for every .mz/ path below.
Parse arguments. Derive two names:
task_name(state dir) =<YYYY_MM_DD>_outreach_research_<slug>where<slug>is a snake_case summary of the goal (max 20 chars) and<YYYY_MM_DD>is today's date with underscores.run_name(outreach output dir) =<YYYY_MM_DD>_outreach_research_<goal_slug>, max 40 chars total (keep<goal_slug>short to fit). Example:"find DevOps clients in DACH"→2026_05_11_outreach_research_devops_dach.
mkdir -p "<PROJECT_ROOT>/.mz/task/<task_name>"
mkdir -p "<PROJECT_ROOT>/.mz/outreach/<run_name>/companies"
Write <PROJECT_ROOT>/.mz/task/<task_name>/state.md:
schema_version: 2
Status: running
Phase: 0
Started: <ISO timestamp>
phase_complete: false
what_remains: []
Goal: <goal>
Sector: <parsed or null>
Region: <parsed or null>
Limit: <limit>
RunName: <run_name> (outreach output dir)
BriefRun: <brief_run or null>
If brief:<run_name> was supplied, read <PROJECT_ROOT>/.mz/outreach/<brief_run>/brief.json and <PROJECT_ROOT>/.mz/outreach/<brief_run>/climate.json and carry their contents into Phase 1. If either file is missing, warn and continue without it — the brief is an enhancement, never a hard dependency. When the goal text is empty but a brief is present, derive the goal from the brief's offering and goal_channels_voice.goal.
After setup completes, read phases/discovery.md and proceed to Phase 1.
State Management
State persists to .mz/task/<task_name>/state.md under the project root, ${MZ_MEMORY_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}, resolved once at the start of the run. Schema is v2: line 1 is schema_version: 2; line 2 is Status: with one of pending, running, blocked, complete, aborted_by_user or failed, lowercase and unquoted; then Phase, Started, phase_complete (boolean) and what_remains (YAML list of strings), with skill-specific keys below them. Milestones go in Phase; the reason for blocked or failed goes in what_remains. Set phase_complete: false on phase entry and true once the phase's artifacts are written and its gates pass. Refresh what_remains on every phase transition; it is [] when Status is complete. Write the file after every phase and before every gate, and re-read it after compaction. Record decisions worth recalling under a heading that reads exactly ## Decisions, placed before ## Notes; mz-memory harvests them only once Status is complete. Under a heading that reads exactly ## Lessons, add one line whenever a review finding is accepted and fixed, a step fails, gate feedback corrects a mistake, or an approved approach is reversed, in the form - (review|failure|correction|change) WHEN <situation> → <what to do> — WHY <cause>, concrete and under about 40 words; mz-memory harvests lessons whatever the Status. Treat a legacy completed as complete. On reading a schema_version: 1 or unversioned file, put schema_version: 2 on line 1 and Status on line 2, add the missing keys, and log the upgrade. Leave a file with a higher schema_version untouched: ask whether to Restart (archive it), start New (_v2) or Abort, and stop if nobody can answer.
Resume Support
Before creating anything in Phase 0, check if <PROJECT_ROOT>/.mz/task/<task_name>/state.md exists for the resolved task_name. If it does, read the Phase field and resume from the next incomplete phase. All phases are idempotent — re-running overwrites output files.
Error Handling
- Agent fails or returns empty: append an
Errors:bullet in<PROJECT_ROOT>/.mz/task/<task_name>/state.md, continue with available data. - All agents in a phase fail (zero results): stop the pipeline and report the failure.
- Never fabricate data — incomplete results are better than false results.
- Corrupted company JSON during any phase: log the error in state.md, skip that company, continue.