market-finder

What this skill does

# Market Finder

Market intelligence powered by Nimble Web Search Agents.

User request: $ARGUMENTS

**Before running any commands**, read `references/nimble-playbook.md` for Claude Code
constraints (no shell state, no `&`/`wait`, sub-agent permissions, communication style).

---

## Instructions

### Step 0: Preflight

Follow the transport selection + standard preflight from `references/nimble-playbook.md` — pick CLI or MCP at session start, then run the standard preflight calls (date calc, today, profile, memory index) in parallel.

Also simultaneously:
- `mkdir -p ~/.nimble/memory/{reports,market-finder/checkpoints}`
- Check for existing checkpoints: `ls ~/.nimble/memory/market-finder/checkpoints/ 2>/dev/null`

From the results:
- CLI missing or API key unset -> `references/profile-and-onboarding.md`, stop
- Tag all `nimble` CLI calls: `nimble --client-source skill-market-finder <subcommand>`. MCP path: not yet supported — see `references/nimble-playbook.md` for status.
- Profile exists -> note industry keywords if any. Apply smart date windowing from
  `references/nimble-playbook.md`. Market-finder tweak: in quick refresh mode,
  skip enrichment and only discover new metros.
- No profile -> fine. Market-finder doesn't require onboarding. Proceed to Step 1.

### Step 1: Parse Request & Detect Mode

Parse `$ARGUMENTS` for business type, geography, qualifiers, and **mode detection**.

#### Mode detection

Check `$ARGUMENTS` for a reference list. Read `references/audit-mode.md` for the
full detection signals and parsing rules.

| Signal | Mode |
|--------|------|
| Google Sheet URL, CSV path, or inline list of 3+ businesses | **Audit** |
| Explicit audit language ("audit my list", "compare against", "gap analysis") | **Audit** |
| No reference list provided | **Discovery** (default) |

If a reference list is present but intent is ambiguous, ask: "Want me to **audit**
your list against fresh discovery, or use it as a starting point?"

If audit language is detected but no reference list is provided, ask: "You mentioned
auditing — please provide your list (Google Sheet URL, CSV file path, or paste inline)."
Do not proceed with Audit mode until a reference list is received.

#### Extract fields

| Field | Required | Source |
|-------|----------|--------|
| Business type / vertical | Yes | User input ("dentists", "SaaS CRM tools") |
| Geography | Yes (except SaaS) | User input ("Florida", "Austin TX", "nationwide") |
| Reference list | Audit mode only | Google Sheet URL, CSV path, or inline |
| Qualification criteria | Optional | User input ("must have website", "10+ reviews") |
| Output preference | Optional | User input ("quick summary", "full dataset") |

**If both type and geography are clear** from `$ARGUMENTS`, confirm briefly and
proceed: "Finding **dentists** in **Florida**..." (or "Auditing your list against
**dentists** in **Florida**..." in Audit mode)

**If partial or ambiguous**, ask one combined question (counts as 1 of max 2
AskUserQuestion prompts):

Use AskUserQuestion with up to 3 questions:
1. **Vertical** -- "What type of business?" with options: Healthcare, SaaS/Software,
   Restaurants/Food, Legal/Financial, Auto/Home Services, Other
2. **Geography** -- "What geography?" (free text or: City, State, Region, Nationwide)
3. **Depth** -- "Quick scan or comprehensive discovery?"

Skip questions already answered by `$ARGUMENTS`.

**Depth modes** (determines how much work each step does):

| Depth | Discovery | Enrichment | Verification | Distribution |
|-------|-----------|------------|-------------|--------------|
| **Quick scan** | All sources, 1 pass | Skip (or top 5 only) | Top 5 entities | Offer |
| **Comprehensive** | All sources + fallback retries | Full | All entities | Offer |

### Step 2: Vertical Detection & Preset Loading

Read `references/vertical-presets.md` and match the user's business type against
preset trigger keywords.

| Match | Action |
|-------|--------|
| Clear match | Load that preset's WSA routing and query pattern |
| Partial match | Confirm: "This looks like **Healthcare**. Use healthcare presets?" |
| No match | Use Custom preset with user's keywords |
| SaaS match | Switch to non-geographic pipeline (no geo-tiling) |

Note which discovery WSAs and enrichment WSAs the preset specifies.

### Step 3: Geographic Scoping

**Skip this step for SaaS vertical** (no geography needed).

| Geography level | Tiling strategy |
|----------------|-----------------|
| City | Single query, no tiling |
| Metro area | Single query per WSA |
| State | Tile by top 5-10 metros in the state |
| Region | Tile by states, then top metros per state |
| Nationwide | Tile by all states, then top metros per state |

**Estimate API calls:** `metros * discovery_wsas * (1 + enrichment_ratio)` where
`enrichment_ratio` is ~0.3. Follow the Scaled Execution pattern from
`references/nimble-playbook.md` to choose execution tier (individual / batch /
multi-batch / confirmation gate):

```
Estimated API calls: ~1,560 (50 states x 8 metros x 3 WSAs + enrichment)
This is a nationwide search. Proceed? [Y/n]
```

Derive a `slug` for checkpointing: lowercase, hyphenated, includes vertical + geo
(e.g., `dentists-florida`, `saas-crm-tools`, `hvac-nationwide`).

### Step 4: Check for Existing Checkpoint

Follow the Checkpointing & Resume pattern from `references/memory-and-distribution.md`.

Check: `cat ~/.nimble/memory/market-finder/checkpoints/{slug}/discovery.json 2>/dev/null`

- **Checkpoint found** -> offer: "Found previous run ({N} entities from {date}).
  Resume and fill gaps, or start fresh?"
- **No checkpoint** -> proceed to Step 5

### Step 5: WSA Discovery & Execution

#### 5a: Discover available WSAs

For each target domain in the selected vertical preset, discover current WSAs:

```bash
nimble agent list --search "{domain}" --limit 20
```

Run these searches simultaneously (one per target domain). From the results:
1. Filter by entity_type (SERP for discovery, PDP/Profile for enrichment)
2. Prefer `managed_by: "nimble"` over `managed_by: "community"`
3. If no WSA found for a domain, mark it for `nimble search` fallback
4. If no WSAs found for ANY domain, fall back entirely to `nimble search` for all metros

Then validate each discovered WSA's input params:
```bash
nimble agent get --template-name {discovered_name}
```

Cache the discovered WSA names + params for the rest of the run.

#### 5b: Geographic discovery (all except SaaS)

For each metro in the tiling plan, run the discovered WSAs simultaneously:

```bash
nimble agent run --agent {maps_wsa} --params '{...validated params...}'
```
```bash
nimble agent run --agent {yelp_wsa} --params '{...validated params...}'
```

Run tertiary domain WSAs only if the preset includes them AND primary + secondary
return < 10 combined unique results for that metro.

Choose execution tier per the Scaled Execution pattern in
`references/nimble-playbook.md` (based on total estimated calls from Step 3).

#### 5c: SaaS discovery (non-geographic)

SaaS skips WSA discovery. Run the two-pass search queries defined in the SaaS
preset from `references/vertical-presets.md`:
- **Pass 1 -- Product discovery:** G2, Capterra, general, ProductHunt, GitHub
- **Pass 2 -- Financial discovery:** Crunchbase, funding news, market landscape

Both passes run simultaneously. Pass 2 is critical -- without it, funding and
traction data will be missing or wrong.

#### 5d: Fallback

If no WSA was found for a target domain, or if a WSA fails for any metro:
```bash
nimble search --query "[type] in [metro]" --max-results 20 --search-depth lite
```

**After discovery:**
1. Parse all results into a unified entity list
2. Deduplicate following the Entity Deduplication pattern from
   `references/nimble-playbook.md`: place_id -> domain -> fuzzy name + city
3. Track `source_count` per entity (how many WSAs/sources found it)
4. Save checkpoint: `~/.nimble/memory/market-finder/checkpoints/{slug}/discovery.json`

### Step 6: Enrichment

Run en