nimbleway/agent-skills/market-finder

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 nimble-agent-skills <subcommand>. MCP requests are attributed at the transport level — see references/nimble-playbook.md.
• 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.

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

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

1. Geography -- "What geography?" (free text or: City, State, Region, Nationwide)
2. Depth -- "Quick scan or comprehensive discovery?"

Skip questions already answered by $ARGUMENTS.

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

Step 2: Vertical Detection & Preset Loading

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

Note which discovery WSAs and enrichment WSAs the preset specifies.

Step 3: Geographic Scoping

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

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:

nimble extract:templates list --limit 100  # then filter items for "{domain}"

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:

nimble extract:templates get --extract-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:

nimble extract:templates run --template {maps_wsa} --params '{...validated params...}'

nimble extract:templates run --template {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:

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

1. Track source_count per entity (how many WSAs/sources found it)
2. Save checkpoint: ~/.nimble/memory/market-finder/checkpoints/{slug}/discovery.json

Step 6: Enrichment

Run enrichment using the WSAs discovered in Step 5a for the preset's enrichment target domains. Prioritize entities with the highest source count first. Choose execution tier per Scaled Execution in references/nimble-playbook.md.

nimble extract:templates run --template {enrichment_wsa} --params '{...validated params...}'

Only run enrichment WSAs that apply to the current vertical's enrichment targets (see references/vertical-presets.md). Skip entities without the required ID/URL for the enrichment WSA.

Save checkpoint: ~/.nimble/memory/market-finder/checkpoints/{slug}/enrichment.json

Step 6b: Financial Verification (SaaS vertical)

For SaaS entities, verify funding claims before reporting. Never label a company's funding stage without a source.

For each entity in the top results (top 5 in quick scan, all in comprehensive):

nimble search --query "{company name} funding raised series" --max-results 5 --search-depth lite

• Source found: Use the sourced amount and date
• No source found: Display "Undisclosed" -- never guess "Early stage" or "Bootstrapped"

This step prevents publishing unverified financial claims. It's fast (one search per entity, lite depth) and catches recent funding rounds that directory sites miss.

Step 7: Deduplication & Scoring

Final deduplication: Run a final dedup pass across all phases following the Entity Deduplication pattern from references/nimble-playbook.md. Merge fields from multiple sources into a single record per entity.

Discovery strength scoring (skill-specific, varies by vertical):

Geographic verticals (Healthcare, Restaurants, Legal, Auto/Home, Custom):

SaaS vertical (funding + directory presence matter more than review count):

Display as: *** High, ** Medium, * Low

Step 7b: Audit Comparison (Audit mode only)

Skip this step in Discovery mode.

Read references/audit-mode.md for the full matching algorithm, normalization rules, and output template.

1. Parse reference list — detect format (Google Sheet / CSV / inline), extract

records, normalize to {name, domain, city, state, phone} per the parsing rules in references/audit-mode.md

1. Run three matching layers in order (domain → name+city → phone). Once an entity

matches at any layer, stop. Track which layer produced the match.

1. Categorize every entity:

• matched — in both reference list and discovery results
• discovered_only — found by discovery, not in reference list
• reference_only — in reference list, not found by discovery

1. Calculate coverage score — matched / reference_count × 100

Proceed to Step 8 with the categorized results.

Step 8: Output

# Market Finder: [Business Type] in [Geography]
*Found [N] businesses | [Date] | Strength: [H] High, [M] Medium, [L] Low*
 
## Summary
- **Total discovered:** [N] unique businesses across [M] metros
- **Geographic breakdown:** [top 5 metros by count]
- **Source coverage:** [list each source used with entity counts]
 
## Top Results (High Strength)
 
| # | Name | Location | Rating | Reviews | Strength | Sources |
|---|------|----------|--------|---------|----------|---------|
| 1 | Acme Dental | Miami, FL | 4.8 | 312 | *** High | Maps, Yelp, BBB |
| 2 | WidgetCo Health | Orlando, FL | 4.6 | 89 | *** High | Maps, Yelp |
...
 
## All Results by Geography
 
### Miami, FL ([n] businesses)
[Table of businesses in this metro]