local-places

What this skill does

# Local Places

Location intelligence powered by Nimble Web Search Agents and web data APIs.

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,local-places/checkpoints}`
- Check for existing checkpoints: `ls ~/.nimble/memory/local-places/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-local-places <subcommand>`. MCP path: not yet supported — see `references/nimble-playbook.md` for status.
- Profile exists -> note the user's location preferences if any. Determine mode
  using smart date windowing from `references/nimble-playbook.md`:
  - **Full mode:** first run OR last run > 14 days ago
  - **Quick refresh:** last run < 14 days ago (skip social enrichment, reviews only
    for new places)
  - **Same-day repeat:** if `last_runs.local-places` is today, check if a report
    already exists at `~/.nimble/memory/reports/local-places-*[today].md`. If so,
    ask: "Already ran today for this area. Run again for fresh data?" Don't silently
    re-run.
  - Skip to Step 1
- No profile -> that's fine. Local places doesn't require onboarding. Proceed to Step 1.

### Step 1: Parse Request & Starting Questions

Parse `$ARGUMENTS` for place type and location. Extract:

| Field | Required | Source |
|-------|----------|--------|
| Place type | Yes | User input ("coffee shops", "gyms", "restaurants") |
| Location | Yes | User input ("Williamsburg", "downtown Austin", "Park Slope") |
| Filters | Optional | User input ("with good reviews", "open late", "cheap") |
| Output preference | Optional | User input ("map", "list", "guide") |

**If both place type and location are clear** from `$ARGUMENTS`, confirm briefly and
proceed: "Searching for **coffee shops** in **Williamsburg, Brooklyn**..."

**If partial or ambiguous**, ask one combined question in plain text:

> "What type of places are you looking for, and where? (e.g., 'coffee shops in
> Williamsburg' or 'gyms near downtown Austin')"

**If the user provided both but you want to scope further**, use AskUserQuestion
(counts as 1 of max 2 prompts):

> **How thorough should this search be?**
> - **Quick scan** -- top results from Google Maps + Yelp (~20 places)
> - **Comprehensive** -- full discovery + social enrichment + reviews (~50+ places)
> - **Deep dive with map** -- everything above + interactive neighborhood map

### Step 2: Location Disambiguation

Before any API calls, resolve the location to avoid wasted searches.

**Disambiguation triggers:**
- Location name exists in multiple cities/states (e.g., "Williamsburg" = Brooklyn NY
  vs. Williamsburg VA)
- Location is a broad area (e.g., "downtown Austin" = multiple neighborhoods)
- Location is informal (e.g., "Soho" = NYC vs. London)

**If ambiguous**, ask the user (counts toward 2-prompt max):

> "There are a few places called **Williamsburg**. Which one?"
> - **Williamsburg, Brooklyn, NY**
> - **Williamsburg, VA**
> - **Other -- I'll specify**

**If unambiguous**, infer the full location (city + state/country) and confirm inline:
"Searching **Williamsburg, Brooklyn, NY**..."

After disambiguation, derive the `slug` for checkpointing and file paths:
lowercase, hyphenated, includes city + state/country (e.g., `williamsburg-brooklyn-ny`).

### Step 3: Check for Existing Checkpoint

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

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

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

### Step 4: WSA Discovery

Discover available WSAs for all phases before execution. Run these searches
simultaneously:

```bash
nimble agent list --search "maps" --limit 20
```

```bash
nimble agent list --search "reviews" --limit 20
```

```bash
nimble agent list --search "social" --limit 20
```

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

From the combined results:
1. Filter by `entity_type`: SERP for discovery, PDP/Profile for enrichment/detail
2. Prefer `managed_by: "nimble"` over `managed_by: "community"`
3. Classify into phases -- see `references/wsa-pipeline.md` for classification strategy
4. Validate each with `nimble agent get --template-name {name}` to confirm params
5. Cache all discovered WSA names + validated params for the rest of the run

If no WSAs found for a phase, that phase falls back to `nimble search`. Log
which phases had WSA coverage and which are using fallback.

### Step 5: Primary Search (Phase 1)

Read `references/wsa-pipeline.md` for category detection logic.

Run discovered maps/location WSAs simultaneously, using the validated params from
Step 4:

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

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

**Tertiary (conditional):** Run discovered credibility WSAs only if primary +
secondary return < 10 combined unique results, or if the user asked for
credibility/trust data.

If any WSA fails or returns empty, fall back to:
`nimble search --query "[place-type] in [location]" --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 exact match -> domain normalization ->
   fuzzy name + city
3. Save checkpoint:
   `~/.nimble/memory/local-places/checkpoints/{slug}/discovery.json`

### Step 6: Social Enrichment (Phase 2)

For each discovered place that has a Facebook page or Instagram handle, run the
social WSAs discovered in Step 4. Batch max **4 concurrent Bash calls**.

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

Run each discovered social WSA for places with matching handles. Skip social
platforms for which no WSA was discovered. If no social WSAs were found in Step 4,
skip this phase entirely.

Save checkpoint: `~/.nimble/memory/local-places/checkpoints/{slug}/social.json`

### Step 7: Reviews (Phase 3)

For the top places (by source count and data completeness), run the review WSAs
discovered in Step 4:

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

Batch max 4 concurrent calls. Focus on places that have a `place_id` or equivalent
identifier from Phase 1 discovery. If no review WSAs were found in Step 4, fall
back to: `nimble search --query "[place-name] reviews" --max-results 5 --search-depth lite`

Save checkpoint:
`~/.nimble/memory/local-places/checkpoints/{slug}/reviews.json`

### Step 8: Food/Drink Bonus (Phase 4)

**Auto-trigger** when the place type category matches food/drink keywords.
See `references/wsa-pipeline.md` for the category detection logic.

If triggered, run the delivery/food WSAs discovered in Step 4. Discovery first,
then detail:

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

For places found on delivery platforms, fetch full details using discovered
detail WSAs:

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

If no delivery WSAs were found in Step 4, fall back to:
`nimble search --query "[place-name] [location] delivery" --max-results 3 --search-depth lite`