Competitor battlecard

Builds the short card. Two to three pages, dense tables, no long prose — the thing a seller skims five minutes before a call and can quote from mid-call.

There is a companion skill, competitor-deep-dive, that builds the long sourced reference document. The two ship as a pair: the card carries the conclusions, the deep-dive carries the evidence. If someone asks for both, build the deep-dive first — the research it forces makes the card sharper — then have the card's closing callout point at it by name.

Shared files live in the plugin's shared/ folder, ../../shared/ from this skill (also ${CLAUDE_PLUGIN_ROOT}/shared/).

Before anything else: the profile

Read competitive-profile.md from the user's working folder. It supplies your company's name, products, differentiators, axis, honest weaknesses and house colours — everything in the "us" column.

If it doesn't exist, stop and run competitive-profile first. A card built without it invents your own side of the comparison, which is the one error that survives into a customer conversation.

Why this format looks the way it does

Three rules are baked into the structure. They came out of real reviews of real competitive documents by the people who had to sell with them, and dropping any of them makes the card worse in a predictable way:

1. Depth belongs in the snapshot table, not in prose. Given a choice between more sections and a richer comparison table, take the table every time.
2. Positioning is one element, not the headline. It gets a single paragraph ("the core message") — never its own section, never a page.
3. Four things must be in the snapshot table — buyer profile, value promise, business-metric connection, and where each side wins. They're in the required rows below, and the one-pager is generated from them.

The section order — header + win condition, core message, snapshot, discovery, reframe, objections, win/walk-away, differentiators — should stay fixed across every card you build. Sellers learn one shape and then find things by position.

Workflow

1. Establish what you actually know. A battlecard asserts things about a real company to a prospect's face, so every claim needs to survive being repeated in a live deal. Gather:

• The competitor's own site: positioning, product pages, pricing, about/team.
• Third-party reviews — the review sites that matter in this category. The complaint inside a positive review is where the sharpest reframes come from.
• Recent news: funding, rebrands, acquisitions, launches. A rebrand or pivot is often the single most useful fact on the card.
• Internal signal, from the tools named in section 8 of the profile: ~~chat for pricing intel and competitive-loss debriefs, ~~knowledge base for your own capability claims, ~~CRM for win/loss reasons.

If a deep-dive already exists for this competitor, read it first and mine it — that's what it's for. Don't redo research that's already sourced.

2. Check your own side. Claims in the "us" column must be things the profile documents, not things the profile aspires to.

3. Write the content file. Copy ../../shared/assets/example-battlecard.json and replace the content. It's a complete worked card, so it doubles as a model of tone and density — every name and number in it is fictional, so replace all of them. Block types are documented in ../../shared/references/content-schema.md.

Set usHeader to the company name from the profile, and copy the theme colours across if the profile defines them.

4. Build it. Set "format": "card" at the top of the content file so the build script checks you against the budget.

cd <plugin>/shared/scripts
npm install docx          # once, if docx isn't already available
node build.js my-card.json ./output/Us_vs_X_Battlecard.docx

It prints total words, the heaviest blocks, a structure check against the rows the one-pager will need, and a claims review — unhedged denials about the competitor, judgement words, undated quotes. Fix length and claims here, before rendering. Trimming a 4-page card to 3 by shaving one line at a time across repeated rebuilds is slow and demoralising.

5. Look at it before sending it. A table that overflows or a cell that swallows its own text is invisible in JSON and obvious in the render.

soffice --headless --convert-to pdf output/Us_vs_X_Battlecard.docx
pdftoppm -jpeg -r 100 Us_vs_X_Battlecard.pdf page

Read the page images. Check: does it land in 2–3 pages? Is the snapshot table on page 1? Any row where the competitor column runs three times longer than ours (usually a sign of unbalanced writing, not unbalanced facts)?

6. Deliver the .docx, and clean up the intermediate .pdf and page-*.jpg.

Length budget

The card is short by design: anything past three pages won't be read. A good card is ~1,600 words across 3 pages. Write to these numbers from the start rather than discovering the overflow at render time.

When good material doesn't fit. If a deep-dive exists, move the detail there and keep only the conclusion on the card. If there's no deep-dive — a standalone card is a perfectly normal request — you have three options, in this order: cut the weakest row of a table entirely rather than shortening every row (a table of half-thoughts is worse than a shorter table); merge two related snapshot rows; or, if the cut material is genuinely valuable, say it's worth a companion deep-dive and offer to build one. Don't compress everything into telegraphic fragments to make it fit.

Required structure

Keep these blocks, in this order. The example file follows it exactly.

The snapshot table's required rows

Adapt the wording to the competitor; don't drop the row. If you genuinely can't source one, keep the row and say what's unknown — "no public per-account seat figure" is useful to a seller; a missing row just looks like it wasn't considered. The build script warns when one of these is missing, because the one-pager is generated from them.

• Primary use case — what they actually sell, in their own framing.
• Buyer profile — who buys it. Segment, vertical tilt, rough scale in the unit that matters in this category, and named customers. "Enterprise" alone is not an answer.
• Main value promise — and specifically, which side of your profile's value-promise axis they sit on. Name it explicitly. That one sentence is usually the whole argument.
• Connects to a business metric? — can they tie their output to a number the buyer's business already reports, with a mechanism rather than a case study? Usually the sharpest gap.
• Pricing model — structure and any real numbers, with provenance marked if the number is secondhand.
• Where they win vs. where we win — both directions, honestly, in one row.

Add competitor-specific rows when the deal turns on something else (integrations, compliance, deployment model, channel coverage) — but keep the table to 9 rows maximum. Past that it stops being scannable and eats the page budget. If a competitor needs more than three extra rows, merge related required rows or push the detail to a deep-dive.

Shading is a heat map — keep it honest

The reader takes in colour before text, so a mis-shaded row actively misleads. Shading defaults to competitor-amber / us-green; override per row with themShade and usShade:

• green — a confirmed, documented strength for whoever's column it's in.
• amber — a gap, a limitation, or an unbacked claim.
• grey — parity, or a claim with no mechanism shown behind it. Use it when neither side clearly wins, rather than defaulting to amber.
• null — no shading; useful for neutral factual rows like pricing structure.

Two rows almost always need an override: the "where they win vs. where we win" row (the competitor cell there describes a genuine win — shade it green or grey, not amber), and any capability the competitor actually has. When you shade a competitor cell green, that's the card working correctly, not a mistake.

Writing rules that make the difference

Acknowledge real strengths, out loud. The reframe section only works if the first clause is true and generous. "Their template engine is genuinely the best in the category" buys the right to say what comes after. A card that treats the competitor as worthless teaches sellers to sound defensive, and prospects who already use the product stop listening.

Attack structure, not quality. "Their reporting is bad" is an opinion a prospect can argue with. "There is no dispute workflow, and their own reviewers name it" is a fact that ends the argument. Prefer gaps that are architectural and durable over gaps a competitor could close in a sprint.

Mark what you don't know. Write "no public evidence of X" rather than "they don't have X" when the research only shows absence. Keep the standing note under the snapshot table. A seller who confidently asserts a missing feature that actually shipped last quarter loses the deal and the card's credibility.

Every discovery question needs a real answer behind it. The "Why It Works" column should name the specific gap the question exposes. A question without a trap behind it is just small talk.

Include genuine walk-away signals. The right-hand column of the win/walk-away table is more useful than the left. "The champion personally chose and rolled out their product" belongs there in bold. Sales trusts a card that tells them when to stop.

Keep cells short. Two or three sentences, ~40 words. If a cell needs a paragraph, that content belongs in the deep-dive, and the card should carry only the conclusion.

When the competitor has your usual differentiators, find a different spine. The profile ranks your differentiators, and they're gaps for many competitors — but not all. A mature competitor may document exactly the thing you usually win on. When that happens, don't stretch to claim an edge that isn't there: shade those rows green in their column, drop them from the differentiators section, and build the card around whatever actually separates you for this competitor. A card that concedes three rows and wins decisively on a fourth is far more useful than one that disputes everything.

Write as though the competitor will read it. Eventually one does. Everything in it should be factual, dated, and defensible — never mocking, never a claim about a named company you couldn't support.

Reference files

• competitive-profile.md (the user's, in their working folder) — your side of every comparison. Read before writing the "us" column.
• ../../shared/references/content-schema.md — every block type and its fields.
• ../../shared/assets/example-battlecard.json — a complete fictional card.