competitor-intel

What this skill does

# Competitor Intelligence

Real-time competitive intelligence powered by Nimble's 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.

From the results:
- CLI missing or API key unset → `references/profile-and-onboarding.md`, stop
- Tag all `nimble` CLI calls: `nimble --client-source skill-competitor-intel <subcommand>`. MCP path: not yet supported — see `references/nimble-playbook.md` for status.
- Profile exists → read `~/.nimble/memory/competitors/index.md` to identify which
  competitor files exist and their last-updated dates. If the index doesn't exist
  (first run or upgrade), fall back to reading all `~/.nimble/memory/competitors/*.md`
  directly — the index is an optimization, not a gate. Then load the relevant
  competitor files for known signals
  (used for dedup in Steps 3 + 5). Follow cross-references (`[[path/entity]]` links)
  to load related context. 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
  - **Same-day repeat:** if `last_runs.competitor-intel` is today, check if a report
    already exists at `~/.nimble/memory/reports/competitor-intel-[today].md`. If so,
    ask: "Already ran today. Run again for fresh data?" Don't silently re-run.
  - Skip to Step 2
- No profile → Step 1

**Note:** Step 2 (WSA Discovery) runs after onboarding but before any research.

### Step 1: First-Run Onboarding (2 prompts max)

**Prompt 1** — ask in plain text (NOT AskUserQuestion with options):

> "What's your company's website domain? (e.g., acme.com)"

Verify — make two Bash calls simultaneously:

- `nimble search --query "[domain]" --include-domain '["[domain]"]' --max-results 3 --search-depth lite`
- `nimble search --query "[domain] company" --max-results 5 --search-depth lite`

**Prompt 2** — confirm company + choose competitor method (use AskUserQuestion):

> I found that **[Company]** ([domain]) is [brief description].
> Is this right? And how should I find your competitors?
> - **Yes — find competitors for me**
> - **Yes — I'll list them myself**
> - **Wrong company — let me clarify**

If "find competitors", make three Bash calls simultaneously:

- `nimble search --query "[Company] competitors" --max-results 10 --search-depth lite`
- `nimble search --query "[Company] vs" --max-results 10 --search-depth lite`
- `nimble search --query "[Company] alternatives" --max-results 5 --search-depth lite`

Propose the list. Once the user confirms, create the profile and start Steps 2+3.
When creating the profile, also ask for or infer each competitor's domain and the
user's industry keywords. See `references/profile-and-onboarding.md` for the full
profile schema (company, competitors with domains/categories, industry_keywords,
integrations, preferences).

### Step 2: WSA Discovery

For each competitor domain and the user's domain, discover available WSAs:

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

Run one search per domain simultaneously. From the results, filter for WSAs with
`entity_type` matching SERP or PDP, prefer `managed_by: "nimble"`, and validate
each with `nimble agent get --template-name {name}`. Cache discovered WSA names +
params for the run. Use discovered WSAs alongside `nimble search` in Steps 3-4
for richer data. If no WSAs found, continue with `nimble search` alone.

### Step 3: Research the User's Company

Use `--include-domain` to avoid noise from generic company names. Make two Bash calls:

- `nimble search --query "product updates OR changelog OR releases" --include-domain '["[company-domain]"]' --start-date "[start-date]" --max-results 5 --search-depth lite`
- `nimble search --query "[UserCompany] news" --focus news --start-date "[start-date]" --max-results 5 --search-depth lite`

**Fallback if < 3 results:** `nimble search --query "blog" --include-domain '["[company-domain]"]' --max-results 5 --search-depth lite`

### Step 4: Parallel Research Per Competitor (sub-agents)

Read `references/competitor-agent-prompt.md` for the full agent prompt template.
Follow the sub-agent spawning rules from `references/nimble-playbook.md`
(bypassPermissions, batch max 4, explicit Bash instruction, fallback on failure).

Spawn `nimble-researcher` agents (`agents/nimble-researcher.md`) with
`mode: "bypassPermissions"`. Customize the prompt template with each competitor's
name, domain, start-date, known signals from memory (loaded in Step 0), and any
discovered WSA names from Step 2 so agents can use them for enrichment.

**Call estimation & Scaled Execution:** Before launching agents, estimate total API
calls: ~6 searches per competitor × N competitors + ~2 industry searches + extractions.
For 2+ competitors (12+ calls), tell agents to use `extract-batch` for page extractions
instead of individual calls. See the Scaled Execution pattern in
`references/nimble-playbook.md` for tier selection.

Also run **industry searches** directly (not in sub-agents), using `industry_keywords`
from the business profile:

- `nimble search --query "[industry_keyword] AI agents OR automation" --focus news --start-date "[start-date]" --max-results 5 --search-depth lite`
- `nimble search --query "[industry_keyword] regulation OR compliance OR pricing" --focus news --start-date "[start-date]" --max-results 5 --search-depth lite`

### Step 5: Deep Extraction

Extract signals that need date verification OR richer detail. See
`references/nimble-playbook.md` → "Signal Date Validation" → "Verification Budget"
for the full rules.

**Must extract:**
- All P1 signals (funding, M&A, leadership) — need confirmed details AND date verification
- Any signal with `DATE_CONFIDENCE: LOW` — event date needs verification from page content
- Any signal where `SOURCE_TYPE: DERIVATIVE` — confirm the event date from the actual
  page content

**Extract if useful:**
- P2 signals where the snippet lacks a date or key detail

**Skip:** P3 signals with `DATE_CONFIDENCE: HIGH`.

Make one Bash call per URL, all simultaneously:

`nimble extract --url "https://..." --format markdown`

For extraction failures, follow the fallback in `references/nimble-playbook.md`.

When reading extracted content, determine the **actual event date** from the article body
(not just the page header date). Look for: explicit dates tied to the event, temporal
language ("last September", "in Q3"), and datelines.

### Step 5.5: Signal Validation

Before building the report, validate every signal's freshness. See
`references/nimble-playbook.md` → "Signal Date Validation" for the full pattern.

**For each signal from Step 3, classify it:**

| Check | Result | Action |
|---|---|---|
| EVENT_DATE within freshness window + not in memory | **NEW** | Include |
| EVENT_DATE within window + updates a known signal | **UPDATED** | Include as update |
| EVENT_DATE outside freshness window | **STALE** | Drop — old event, new article |
| DATE_CONFIDENCE: LOW + couldn't verify in Step 4 | **UNCERTAIN** | Drop with note |

**P1 corroboration (mandatory)** — any P1 signal with `NEEDS_CORROBORATION: true` MUST
be corroborated before it can enter the report. This is a hard gate, not a suggestion.

For each flagged P1, run:

`nimble search --query "[Company] [event summary]" --max-results 5 --search-depth lite`

Look for the **primary source** (company blog, press release, official filing). If the
primary source dates the event outside the freshness window, reclassify as STALE.
If no primary source is found, reclassify as UNCERTAIN and drop.

**Drop rules:**
- Event d