competitor-intel

# 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 date is outside the freshness window → STALE
- Only sourced from derivative/aggregator sites with no corroborating primary or major
  outlet → UNCERTAIN, drop unless verified via extraction
- Content clearly describes a past event (temporal language like "last year", "back in Q3",
  "months ago") with event date outside the window → STALE

After validation, you should have a clean list of NEW and UPDATED signals only.

### Step 6: Analysis & Output

**Full mode** (first run or > 14 days since last) — structured briefing:

- **TL;DR** — 3-5 P1 signals, most recent first, every one dated with source
- **Per competitor** — "Recent" and "Older Context" subsections, "Where They Win
  vs. Where You Win" table, "What This Means" (1-2 sentences)
- **Industry Trends** — signals from industry searches
- **Your Company Update** — releases/news from Step 2
- **Cross-Competitor Patterns** — converging trends
- **What This Means for [Company]** — strategic implications + suggested actions

**Quick refresh mode** (last run < 14 days) — short format:

- **New Signals** — dated, with competitor name, priority, and clickable source URL
- **Nothing New** — list competitors with no new signals
- **Action Items** — only if something requires attention

**Core rules:**
- Every signal MUST have a verified **event date**. Only events that happened within the
  freshness window qualify as new signals — older events are background context.
- Only include signals classified as NEW or UPDATED in Step 5.5. STALE and UNCERTAIN
  signals have already been dropped.
- Deduplicate against `~/.nimble/memory/competitors/*.md` — only surface NEW findings.
- Say "nothing notable this period" rather than padding with fluff.
- P3 signals: mention briefly or omit if report is long.

### Step 7: Save & Update Memory

**Only persist signals that passed Step 5.5 validation** (classified as NEW or UPDATED).
Do not write STALE or UNCERTAIN signals to competitor memory files.

Make all Write calls simultaneously:

- Report → `~/.nimble/memory/reports/competitor-intel-[date].md` (save the **full
  briefing**, not a summary — this is the local source of truth)
- Per competitor → append validated signals to `~/.nimble/memory/competitors/[name].md`
  (use the format documented in `references/memory-and-distribution.md`). Add
  `[[path/entity]]` cross-references for relationships discovered during research
  (e.g., key people → `[[people/name]]`, related competitors → `[[competitors/name]]`).
- Profile → update `last_runs.competitor-intel` in `~/.nimble/business-profile.json`
- Follow the wiki update pattern from `references/memory-and-distribution.md`: update
  `index.md` rows for all affected entity files, append a `log.md` entry for this run.

### Step 7.5: Synthesis Page Generation

If 3+ competitors were researched in this run, OR the existing
`~/.nimble/memory/synthesis/competitive-landscape.md` has stale source timestamps
(source entity files were updated since generation), generate or refresh the synthesis
page.

Use the `nimble-analyst` agent (`agents/nimble-analyst.md`) with
`mode: "bypassPermissions"` to synthesize patterns across all competitor files. The
agent should read all `~/.nimble/memory/competitors/*.md` files and produce a
`competitive-landscape.md` following the format in
`references/memory-and-distribution.md` — market map, feature comparison, pricing
comparison, key patterns, and strategic implications. Cite source entity files with
`[[competitors/name]]` links.

Also append any unanswered questions to `~/.nimble/memory/backlog.md`
(e.g., competitors where key data like pricing or funding is missing).

After generating, update `index.md` with the synthesis page entry.

### Step 8: Share & Distribute

**Always offer distribution — do not skip this step.** Follow
`references/memory-and-distribution.md` for connector detection, sharing flow, and
source links enforcement.

### Step 9: Follow-ups

- **Go deeper** on a competitor → more focused searches
- **Skip a competitor** → update `preferences.skip_competitors`
- **Add a competitor** → update `competitors`, create memory stub
- **"Looks good"** → done

**Sibling skill suggestions:**

> **Next steps:**
> - Run `competitor-positioning` to analyze how competitors present themselves online
> - Run `company-deep-dive` for a full 360 profile on any competitor from this report
> - Run `meeting-prep` if you're meeting with someone at a competitor

---

## Agent Teams Mode (Dual-Mode)

Check at startup: `echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`

**Team mode** (flag set): Spawn full **teammates** instead of sub-agents:

- **Lead** (you): Assign competitors, synthesize the final briefing
- **One teammate per competitor**: Uses `references/competitor-agent-prompt.md` with discovered WSAs —
  teammates can message each other when they find overlapping signals
- **Devil's Advocate** (optional): Challenges findings, looks for blind spots
- Lead synthesizes a **cross-validated** briefing with higher confidence

**Solo mode** (flag not set): Standard sub-agent flow from Step 3.

---

## Error Handling

See `references/nimble-playbook.md` for the standard error table (missing API key, 429,
401, empty results, extraction garbage). Skill-specific errors:

- **Search 500:** Retry once without `--focus` flag. If still failing, retry with a
  simplified query (shorter terms, no date filter). Log the failure but don't skip
  the competitor.
- **Search timeout:** Retry once, then skip that call and continue — consistent with
  the playbook's timeout policy.