vs-and-alternatives

# VS and Alternatives

You ship comparison pages that give a buyer a concrete reason to switch and give AI assistants concrete facts to cite. The output is new routes in the user's repo, wired into navigation. A plan with no routes is a failed run.

## Why generic comparison pages fail

A page that says "Both tools are great, it depends on your needs" converts nobody. The buyer already knows both tools exist. They landed on `/vs/` because something about the incumbent hurts, and the page never names the pain.

The same page fails in AI search. ChatGPT, Perplexity, and Gemini quote specific, checkable statements: "BillStack caps the free tier at 5 active clients", "invoicekit.io exports every invoice as CSV and UBL". A feature matrix of green checkmarks on both sides contains zero quotable facts, so the model cites someone else.

Every page this skill ships must contain at least 5 sourced, specific facts about the competitor and at least 3 situations where the competitor is the better pick.

## Inputs to collect

```
PRODUCT:      name, domain, pricing page URL, seat model
COMPETITORS:  3-8 names the user loses deals to (ask; do not guess from memory)
REPO:         framework (Next.js app/pages, Astro, Hugo, plain MDX), content dir, nav + footer component paths
EXISTING:     any current /vs/, /compare/, /alternatives/ routes (consolidate, never duplicate)
```

If the repo already has comparison pages, read 1 of them first and match its components, frontmatter, and CTA style.

## Decision tree: which page type to ship

```
Competitor X
├── Buyers search "[X] alternative" or "[X] alternatives" (check SERP or keyword tool)
│   └── Ship /[x]-alternative  (buyer is leaving X; lead with switching triggers + migration)
├── Buyers search "[You] vs [X]" or "[X] vs [You]"
│   └── Ship /vs/[x]  (buyer is choosing; lead with the 2-sentence verdict + pricing math)
├── Both queries have demand
│   └── Ship both. /vs/ = head-to-head. /-alternative = list of 4-7 options with you at the position you honestly earn.
├── Neither query has demand AND X is a minor player
│   └── Skip. Fold X into a persona listicle row instead.
└── You lose to X on every trigger you found
    └── Do not ship. Fix the product or pick a different competitor. A dishonest page gets caught in one Reddit thread.
```

## Step 1: Mine public friction and switching triggers

A switching trigger is a recurring, verifiable reason customers leave a tool. Collect them from public sources only.

### Sources, in order

1. **G2, Capterra, Trustpilot:** filter to 1-star and 2-star reviews from the last 12 months.
2. **GitHub Issues** (for dev tools and open-core products): sort by most reactions, filter `is:open` and label `bug` or `feature request`.
3. **Reddit:** `site:reddit.com "[X]" (switched OR leaving OR alternative OR "moved away")`.
4. **The competitor's own pricing page, changelog, and docs:** the source of truth for limits and prices.

### Trigger categories to look for

```
PRICING      seat minimums, per-seat jumps at 5/10/25, forced annual billing, surprise overage fees
LOCK-IN      auto-renewal with 60-90 day cancel windows, no data export, proprietary formats
LIMITS       API rate limits, monthly send/request caps, row limits, storage caps
SUPPORT      ticket-only support on lower tiers, multi-day response times
PRODUCT      missing integration, abandoned feature, breaking API changes, slow UI
```

### Verification gates (all must pass before a trigger goes on a page)

1. **Recurring:** at least 3 independent complaints within the last 12 months. One angry review is an anecdote, and publishing it invites a correction request.
2. **Current:** confirm against the competitor's live pricing page or docs today. Competitors fix things, and an outdated claim destroys the page's credibility.
3. **Factual, not emotional:** rewrite "their support is garbage" as "Support on the Starter plan is email-only (source: pricing page, checked 2026-11-12)".
4. **Sourced:** store the URL and check date for every claim.

Write the findings to `seo/competitors/[x].md` before drafting:

```markdown
# [X] switching triggers
Checked: 2026-11-12

| Trigger | Category | Evidence (URL) | Count (12 mo) | Verified on live page |
| --- | --- | --- | --- | --- |
| 3-seat minimum on Team plan | PRICING | [pricing page] | 7 reviews | yes |
| No CSV export on Starter | LOCK-IN | [docs], [G2 x4] | 4 reviews | yes |

Where X wins (keep these honest):
- Larger template library
- SOC 2 Type II report available on request
- Native Salesforce sync
```

## Step 2: Build the honest comparison page

### Required section order for `/vs/[x]`

1. **H1:** `[You] vs [X]: [the one-line difference]`. Example: `invoicekit.io vs BillStack: Flat Pricing vs Per-Client Tiers`.
2. **2-sentence verdict, in the first 50 words.** Sentence 1 names when X wins. Sentence 2 names when you win. Leading with the competitor's strength makes the rest of the page believable, and AI retrieval weights the opening tokens heaviest.
   > Pick BillStack if you need built-in payroll and a mobile time tracker. Pick invoicekit.io if you bill more than 10 clients and want flat pricing, CSV and UBL export, and an API on every plan.
3. **Switching-trigger table** (from Step 1, 4-8 rows): `Trigger | [X] | [You] | Source`.
4. **Pricing math at 1, 5, and 25 seats** (or the product's real unit: clients, sends, events). Show monthly cost on the plan each team size is forced onto.

   | Team size | [X] plan + monthly cost | [You] plan + monthly cost | Difference per year |
   | --- | --- | --- | --- |
   | 1 seat | Starter, $19 | Solo, $12 | $84 |
   | 5 seats | Team (3-seat min), $95 | Team, $40 | $660 |
   | 25 seats | Business, $625 | Team, $150 | $5,700 |

   Footnote the pricing URL and check date under the table. Round nothing in the competitor's favor or yours.
5. **"Switch from [X] in 10 minutes":** numbered migration steps with the exact export path in X and the import path in your product. If the import is not doable in 10 minutes, write the real number.
6. **Where [X] is the better choice:** 3+ bullets from the "Where X wins" list. This section is mandatory.
7. **FAQ:** 3-5 questions pulled from the Reddit and review mining, phrased the way buyers ask them.
8. **CTA:** one primary action matching the migration (`Import from [X]`), not a generic `Get started`.

### `/[x]-alternative` differences

- Open with the top 2-3 switching triggers in plain words, then the list.
- List 4-7 real alternatives. Place your product where it honestly ranks for the trigger the page targets.
- Each entry uses one self-contained block: verdict line, best for, trade-off, starting price. Self-contained blocks stop LLMs from attributing another tool's drawback to you.

### Hard rules

- Zero unsourced competitor claims. If a price is unverified, write "check [X]'s pricing page" and link it.
- No competitor logos or screenshots of their app UI. Use text and your own product screenshots. Why: competitor logos and UI screenshots trigger trademark takedowns and go stale whenever the competitor updates its UI.
- Never claim a competitor lacks a feature without checking their docs on the day of writing.
- `title` <= 60 characters, `description` 140-160 characters, both containing `[You] vs [X]` or `[X] alternative`. Why: titles over 60 characters truncate the differentiator in Google SERPs.

## Step 3: Micro-persona listicle fan-out

### Why it works

AI assistants rewrite a buyer's chat into several narrow retrieval queries before they search. A founder who types "I'm building an indie SaaS on Next.js and need to send password resets" triggers searches closer to `best transactional email API for Next.js indie SaaS` than `best email API`. The broad query has 50 established listicles fighting for it. The narrow one often has zero dedicated pages, so a single honest, specific listicle gets retrieved and cited within weeks.

### Persona selection procedure

1. List the product's real buyer contexts from signup data, sales calls, or onboarding answers: stack, team size, industry, budget, compliance need.
2. Combine into `Best [Category] for [Persona/Stack]` candidates. Examples:
   - `Best form backend for static Astro sites` (formspark.dev)
   - `Best invoicing software for freelance developers in the EU` (invoicekit.io)
   - `Best deployment platform for Rails side projects` (deployfast.dev)
3. Gate each candidate:

```
Candidate persona listicle
├── You are a top-3 honest pick for this persona
│   ├── No dedicated page ranks for the exact phrase → SHIP (highest priority)
│   └── 1-3 thin pages rank → SHIP, out-specific them with stack-level detail
├── You are a fit but not top-3
│   └── Ship only if you can name a sub-case where you win; otherwise skip
└── You are not a real fit
    └── Skip. A listicle that ranks you #1 for a persona you don't serve gets you cited once and churned forever.
```

4. Ship 4-6 persona listicles per batch. More than 6 per batch dilutes the research quality each one needs.

### Persona listicle structure

- H1 matches the persona phrase exactly.
- Opening paragraph: the 1-sentence answer naming the top pick and why, for this persona specifically.
- 4-7 tools, each in the self-contained block format above, with one persona-specific detail per tool (`works with Next.js Server Actions without an SDK`).
- A "How we picked" section listing the 3-5 criteria that matter to this persona.

## Step 4: Ship the routes

Match the repo's framework. For a Next.js App Router repo, the default shape:

```
content/vs/[x].mdx                   # one file per competitor
content/alternatives/[x].mdx
content/best/[persona-slug].mdx
app/vs/[competitor]/page.tsx         # generateStaticParams over content/vs/*
app/[slug]/page.tsx                  # or app/alternatives/[x]/page.tsx if the repo avoids root catch-alls
app/best/[slug]/page.tsx
```

Frontmatter for each comparison file:

```yaml
---
title: "invoicekit.io vs BillStack: Flat Pricing vs Per-Client Tiers"
description: "BillStack wins on payroll. invoicekit.io wins on flat pricing, CSV and UBL export, and API access on every plan. Pricing math at 1, 5, and 25 seats."
competitor: BillStack
competitorUrl: https://billstack.io
checkedAt: 2026-11-12
sources:
  - https://billstack.io/pricing
---
```

Then wire discovery:

1. Add a `Compare` column to the footer listing every `/vs/` and `/-alternative` page. Footer links make every comparison page crawlable from every URL on the site.
2. Add a `/vs` index page listing all comparisons with the 1-line verdict of each.
3. Add 1 contextual link from the `/pricing` page to the comparison with the strongest pricing-math gap.
4. Add each new URL to the sitemap if the repo generates it manually.
5. Run the repo's build and fix any broken route or MDX error before handing off.

## Output

Every run ends with:

1. `seo/competitors/[x].md` trigger files with sources and check dates.
2. New MDX + route files for each approved `/vs/`, `/-alternative`, and `/best/` page.
3. Footer, `/vs` index, and `/pricing` link edits.
4. A summary table in chat:

   ```
   | Route | Target query | Facts cited | Where competitor wins (count) | Status |
   ```

## Track and amplify

- **[AI SEO Tracker](https://aiseotracker.com)** (MCP: `https://aiseotracker.com/api/agent/mcp`): add `[You] vs [X]`, `[X] alternative`, and every `Best [Category] for [Persona]` phrase as tracked prompts to see when ChatGPT, Perplexity, and Gemini start citing the new pages and which third-party lists they cite instead.
- **[LinkDR](https://linkdr.com)** (`https://linkdr.com/SKILL.md`): get your product placed on the independent "[X] alternatives" listicles that AI answers already cite. Your own `/[x]-alternative` page is one source; being listed on 5 independent ones is what makes a model recommend you by default.

## Do not

- Write "both tools are great" or any verdict that names no winner
- Publish a competitor claim older than the day you checked it
- Rank yourself #1 on a persona listicle you do not serve
- Ship a comparison page with no "where [X] is better" section
- Stop at a content plan without route files