Docs Comparison Pages

---
name: docs-comparison-pages
description: >
  Write honest "X vs Y", "alternatives to X", and "migrate from X" pages from
  verified facts, each unique and dated for review. Use when "comparison
  page", "vs page", "alternatives to", "competitor page", or "migration guide
  from".
license: MIT
effort: high
---

# docs-comparison-pages — The pages buyers read last

**Degree of freedom: MIXED.** Which competitors and angles `[HIGH freedom]`;
fact verification, per-page uniqueness, and the freshness contract
`[LOW freedom — run exactly]`.

Apply-now. In one 162-page programmatic test, comparison pages were 28% of
the pages and took 78% of the clicks and six of seven leads. They also sit
squarely inside Google's scaled-content-abuse policy when generated in bulk.
This skill writes a few pages that survive both a buyer and a reviewer.

## This skill vs neighbors

| Skill | Owns |
|---|---|
| **docs-comparison-pages** (this) | Comparison / alternatives / migration page content and its freshness contract |
| `enhance-web-seo` | Title, meta, canonical, JSON-LD, sitemap for those pages |
| `plan-aeo-readiness` | Whether answer engines can read and cite them |
| `docs-writer` | Product docs and the migration steps' technical accuracy |
| `plan-antislop` | Voice audit when a page reads generated |
| `docs-launch-kit` | Launch posts — not evergreen pages |

Do **not** fire for "write a blog post about our launch" → `docs-launch-kit`.

## How to reason

1. **Query** — which bottom-funnel question does a real buyer type, and which alternative do they name?
2. **Facts** — every claim about the competitor comes from their current public page, dated
3. **Angle** — where is the product honestly better, honestly worse, and for whom
4. **Unique** — what on this page could not be pasted onto the next one
5. **Freshness** — who re-verifies competitor prices and features, and when

## Worked example

> **Query:** "mushi-mushi vs Sentry user feedback" — buyers name Sentry.
> **Facts:** Sentry pricing page fetched 2026-09-17; free tier limits quoted with the date; our limits from `pricing.ts`.
> **Angle:** better for in-app screenshot + reporter chat; worse for backend error grouping; for teams shipping web apps without a support desk.
> **Unique:** a side-by-side of one real bug report in both tools; the migration snippet from their SDK init to ours.
> **Freshness:** `lastVerified: 2026-09-17`, review quarterly; page shows "prices checked on …".

## Self-critique before reporting

- **Dated facts** — every competitor claim carries the fetch date and URL in the source block
- **Both directions** — the page names at least one thing the alternative does better
- **No template stamping** — two pages share structure, never paragraphs
- **Freshness contract** — `lastVerified` in frontmatter and a visible "checked on" line; review cadence recorded
- **Right owner** — meta/schema → `enhance-web-seo`; voice → `plan-antislop`

---

## Procedure

### 1. Choose pages  [HIGH freedom]

From `plan-gtm`'s alternatives list (or the founder), pick ≤5 pages to start:
`<product> vs <alt>`, `<alt> alternatives`, `migrate from <alt>`. One page per
real query; skip alternatives nobody compares against.

### 2. Verify facts  [LOW freedom — run exactly]

For each alternative: fetch its pricing page, feature/limits page, and docs this session (Firecrawl or WebFetch) — recognizing the product's name is not knowing its current prices or limits, so fetch even for products you know well. Record `URL · fetched date · quote` in a source
block at the bottom of the page. Product-side facts come from the repo
(`pricing`, limits, feature flags) with file references. Anything
unverifiable is omitted, not softened.

### 3. Write  [HIGH freedom — words; LOW freedom — shape]

Shape per page (order may vary, sections may not be skipped):

1. **Verdict in two sentences** — who should pick which.
2. **Comparison table** — 6–10 rows buyers care about; ✅/⚠️/❌ plus one clause each; prices with the checked-on date.
3. **Where the alternative wins** — honest, specific.
4. **Where this product wins** — with a screenshot or a real artifact.
5. **Migration** (migrate-from pages) — steps, code, data export/import, what does not carry over.
6. **FAQ** — 3–5 real objections (→ FAQ JSON-LD via `enhance-web-seo`).
7. **Sources** — the dated block from step 2.

Voice: first person plural, plain claims, no superlatives, no mannered prose (throat-clearing openers, stacked hedges, triplets for rhythm, a closing line that restates the paragraph). If a paragraph
could sit on another vendor's page, rewrite it.

### 4. Freshness contract  [LOW freedom — run exactly]

Frontmatter `lastVerified: YYYY-MM-DD`, `reviewEvery: 90d`; visible line
"Prices and limits checked on …". Add a repo reminder (issue, cron, or
`docs/launch` calendar row) for the next review. A page past its review date
gets re-verified or unpublished — never left stale.

### 5. Hand off

`enhance-web-seo` for title/meta/canonical/JSON-LD and sitemap;
`plan-aeo-readiness` if answer-engine citation is a goal; `test-playwright`
for the migration snippet where it is runnable.

## Guardrails

- **No bulk generation.** ≤5 pages per pass, each hand-checked; templated batches are the spam policy's target.
- **No trademark misuse.** Competitor names as plain text; their logos only with permission.
- **No invented weaknesses.** If you cannot cite it, it is not on the page.
- **Keep the loser's case.** A page with no "where they win" section is not published.

## Chains with

- **`plan-gtm`** → alternatives list and channel plan.
- **`enhance-web-seo`** → meta, schema, sitemap.
- **`plan-aeo-readiness`** → citation readiness.
- **`docs-launch-kit`** → announce a new comparison page in the next kit.