# Competitor positioning Human Guide

## What This Is For
Marketing-focused competitive positioning analysis powered by Nimble's web data APIs. It gives the agent a clearer input/output frame for brand and messaging: what context to ask for, what decisions to make, and what usable artifact to return.

Use this as a human-readable version of the Competitor positioning agent skill. It is meant for marketers, operators, founders, and other non-coders who want the workflow without reading agent-specific implementation instructions.

## When To Use This
- Use this when you need a repeatable process for competitor positioning.
- Use this when the task needs judgment, examples, constraints, or a clear output format rather than a one-off prompt.
- Use this when you want to hand an AI assistant enough context to produce a usable marketing artifact.

## When Not To Use This
- Do not use this when you only need a quick factual answer.
- Do not use this when the work depends on private data you cannot share with the assistant.
- Do not use this as a replacement for legal, compliance, financial, or medical review.

## What You Need Before Starting
- The goal or business outcome you want.
- The audience, customer segment, or market context.
- Any source material the assistant should respect, such as notes, briefs, examples, URLs, or brand guidance.
- Constraints such as tone, length, channel, deadline, region, or approval requirements.
- A clear definition of what a good final answer should look like.

## Step-By-Step Workflow
1. State the job clearly: "Use the Competitor positioning guide to help me with..."
2. Add context: audience, goal, offer, channel, source material, and constraints.
3. Ask the assistant to identify missing inputs before producing the final output.
4. Have the assistant follow the skill-specific guidance below.
5. Review the result against the final checklist and ask for revisions where needed.

## Skill-Specific Guidance
- No arguments → run full workflow (scope confirmation in Step 2)
- Competitor names (e.g., "Exa, Tavily") → research only those, skip scope confirmation
- "battlecard [competitor]" → skip to Battlecard Generation (see below) using
- "delta" / "what changed" → force delta mode regardless of timing
- CLI missing or API key unset → `references/profile-and-onboarding.md`, stop
- Tag all `nimble` CLI calls: `nimble --client-source skill-competitor-positioning <subcommand>`. MCP path: not yet supported — see `references/nimble-playbook.md` for status.
- Profile exists → load prior data from two sources:
- `~/.nimble/memory/positioning/*.md` — prior positioning snapshots (used for
- `~/.nimble/memory/competitors/*.md` — business signals from competitor-intel
- **Full snapshot:** first run OR no prior positioning data OR last run > 14 days ago
- **Delta mode:** last run < 14 days ago — only surface what changed
- **Same-day repeat:** if `last_runs.competitor-positioning` is today, check for

## Decision Points And Nuance
The original skill emphasizes: Instructions, Step 0: Preflight, Step 1: First-Run Onboarding (2 prompts max), Step 2: Confirm Scope, Step 3: WSA Discovery, Step 4: Capture the User's Own Positioning (baseline), Step 5: Parallel Research Per Competitor (sub-agents), Step 6: Analysis & Output, Step 7: Save & Update Memory, Step 8: Share & Distribute.

Use these questions to steer the work:
- What is the intended audience or buyer?
- What source material must be preserved?
- What should the assistant optimize for: clarity, persuasion, accuracy, speed, creativity, or conversion?
- What examples represent the desired quality bar?
- What should the assistant avoid?

## Common Mistakes
- If found, ask: "Already ran today. Run again for fresh data?" Don't silently re-run.
- Do NOT use `agents/nimble-researcher.md` — that agent is scoped for raw data gathering
- Site structure signals (what pages exist/don't exist, subdomains)
- Topics they cover that you don't
- Every claim must link to the source page.
- Use verbatim quotes for taglines, CTAs, and value props — don't paraphrase.
- **Always offer distribution — do not skip this step.** Follow
- simplified query (shorter terms, no date filter). Log the failure but don't skip

## Copy-And-Paste Prompt
```text
Use the Competitor positioning human guide.

My goal:
[Describe the business outcome]

Audience:
[Describe who this is for]

Context and source material:
[Paste notes, examples, links, or existing copy]

Constraints:
[Tone, length, channel, timeline, must-include items, must-avoid items]

Before producing the final output, ask me for any missing information that would materially improve the result.
```

## Final Checklist
- [ ] The output matches the original goal.
- [ ] The audience and context are reflected in the answer.
- [ ] Important constraints and source material were preserved.
- [ ] The assistant made the relevant decisions explicit.
- [ ] The final artifact is ready to use, review, or hand to the next person.

## Source
This guide was generated from the nimbleway/agent-skills skill entry for `competitor-positioning`.

## Source Skill Notes
These notes preserve the nuance from the original skill. Use them as supporting reference when the workflow above feels too generic.

# Competitor Positioning

Marketing-focused competitive positioning analysis powered by Nimble's web data APIs.
Built for marketing teams who need to understand how competitors present themselves —
messaging, value props, content themes, pricing — and how that evolves over time.

The output is a **marketing briefing**, not a signal feed. Every insight should answer:
"what does this mean for our messaging and positioning?"

User request: $ARGUMENTS

**Argument parsing** — determine what to do before running anything:
- No arguments → run full workflow (scope confirmation in Step 2)
- Competitor names (e.g., "Exa, Tavily") → research only those, skip scope confirmation
- "battlecard [competitor]" → skip to Battlecard Generation (see below) using
  existing snapshots from memory
- "delta" / "what changed" → force delta mode regardless of timing

**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-positioning <subcommand>`. MCP path: not yet supported — see `references/nimble-playbook.md` for status.
- Profile exists → load prior data from two sources:
  - `~/.nimble/memory/positioning/*.md` — prior positioning snapshots (used for
    delta detection in Steps 4 + 5)
  - `~/.nimble/memory/competitors/*.md` — business signals from competitor-intel
    runs (provides context for *why* positioning may have shifted, e.g., a funding
    round or leadership change that preceded a messaging pivot)
  Determine mode:
  - **Full snapshot:** first run OR no prior positioning data OR last run > 14 days ago
  - **Delta mode:** last run < 14 days ago — only surface what changed
  - **Same-day repeat:** if `last_runs.competitor-positioning` is today, check for
    existing report at `~/.nimble/memory/reports/competitor-positioning-[today].md`.
    If found, ask: "Already ran today. Run again for fresh data?" Don't silently re-run.
  - Skip to Step 2
- No profile → Step 1

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

This skill shares the competitor list from `competitor-intel`. If a profile already
exists with competitors, skip onboarding entirely.

If no profile exists, follow `references/profile-and-onboarding.md` for the full
onboarding flow. The profile and competitor list created here will be shared across
all business skills.

### Step 2: Confirm Scope

If `$ARGUMENTS` already specifies competitors, use those and skip this step.

Otherwise, check how many competitors are in the profile:
- **4 or fewer** → proceed with all, no confirmation needed
- **More than 4** → ask which to focus on (use AskUserQuestion):

  > You have [N] competitors tracked. Which ones should I analyze?
  > - **All [N]** (~[3-5 × N] Nimble API credits, ~[N × 2] min)
  > - **[Category A]**: [names] (grouped by `category` from profile)
  > - **[Category B]**: [names]
  > - **Let me pick** — I'll list them

  Accept natural language: "just the AI search ones" → resolve from profile categories.

This prevents wasted API credits and wall time on competitors the user doesn't care
about right now. Each competitor costs ~3-5 Nimble API credits (1 map + 3-4 extracts
+ 2-3 searches).

### Step 3: WSA Discovery

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