Competitor deep-dive

Builds the long document — the one nobody reads before a call and everybody reads before a strategy decision, an RFP response, or when a seller needs to check whether a claim on the battlecard is actually true.

Its companion, competitor-battlecard, builds the 2–3 page sales card. When both are wanted, build this one first: the research forces the precision that makes the card sharp, and the card can then cite this document 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. Sections 7 and 8 of this document compare the competitor against your products one at a time, and that pairing is the analytical spine — it can't be written without knowing what your products are and what they're documented to do.

If no profile exists, stop and run competitive-profile first.

What makes this document worth writing

The value is not length. It's that every external claim carries a date, a source and a link, so six months later a reader can tell what's still true. A deep-dive full of confident unsourced assertions is worse than nothing — it launders guesses into internal fact.

Three habits carry most of that weight:

Date everything. A review from ten years ago and one from last month tell you opposite things about whether a complaint was ever fixed. When the same complaint appears in both, that's the finding — a decade-long pattern, not an anecdote.

Say when you don't know. "No public evidence of X" and "X doesn't exist" are different claims. Use the first unless you've actually verified the second. Give the document a confidence-and-methodology section that admits what was blocked, approximate or secondhand.

Name real strengths. The "where they genuinely have an edge" section is what makes the rest credible. A reader who sees a competitor described as having no redeeming qualities correctly discounts the whole document.

Workflow

1. Research before touching the format. Don't open the build script until you have the material. Read references/research-playbook.md — it lists where to look, in what order, and how to handle sources that block automated fetching.

2. Re-read the profile so the "us" columns in sections 7 and 8 cite documented capability rather than aspiration.

3. Write the content file. Copy ../../shared/assets/example-deepdive.json and replace the content — it's a working example of the full structure, fictional and deliberately condensed, so replace every name and number in it. Block types are in ../../shared/references/content-schema.md. Set usHeader per table to the specific product being compared, and copy the profile's theme colours if it defines any.

4. Build.

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

The build prints a length report and a claims review: unhedged denials about the competitor, judgement words, and any quote whose attribution carries no date. Treat the undated-quote warnings as blocking — an undated quote can't be re-checked, which defeats the point of the document.

5. Render and read it. Long documents break in ways JSON hides — a table running past the page edge, a section landing alone at the bottom of a page.

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

Read every page image. Then check three things that are easy to get wrong and embarrassing to ship: is every quote attributed to the platform it actually came from, does every claimed link resolve to the right page, and does the source list at the end include everything cited inline?

Don't hand-place page breaks to tidy the layout. Section lengths shift as you edit, and a fixed break almost always strands one orphan row at the top of an otherwise empty page. Let the document flow — table rows already carry cantSplit, so no individual row splits across pages.

6. Deliver the .docx and clean up intermediate files.

Document structure

Twelve sections. Renumber if a section doesn't apply — a competitor with no rebrand doesn't need section 2.1 — but keep the order, because the pairing of sections 7 and 8 against your own products is the analytical spine.

Depth to aim for

Sections 5 and 6 are where readers decide whether the document is real. Aim for 8–12 individual reviews per platform in the tables, spanning the widest date range available, each with its own date. Include reviews that contradict each other and say so — an early review praising "powerful reporting" sitting next to a decade of reporting complaints is a finding worth a sentence, not a problem to hide.

Handling the awkward parts

Reviews often have no permalink. Most review platforms don't expose a stable URL per individual review. Link the product review page and say once, in the methodology section, that the page is the closest available reference for each quote. Don't fabricate anchors.

Some sources block automated fetching. Vendor pricing pages especially. When a fetch fails, don't substitute a guess — link the page so the reader can check it, and note in section 4 and section 11 that it couldn't be retrieved. Never work around a blocked fetch with a different fetching method.

Internal intel needs marking as internal. Pricing from a deal recap in ~~chat is genuinely useful and genuinely unverified. Cite the thread, label it secondhand, and link the vendor's own page next to it.

Dates extracted from rendered pages are approximate. Say so in the methodology section. If one date looks wildly out of pattern, omit that review rather than guessing at it — and mention that you did.

Write as though the competitor will read it. Eventually one does. This document should read like evidence, not advocacy: no mockery, no unsourced characterisation of a named company, nothing you'd be uncomfortable defending.

Reference files

• references/research-playbook.md — where to look, in what order, and what to extract. Read this first.
• competitive-profile.md (the user's, in their working folder) — your products and their documented capabilities, for sections 7 and 8.
• ../../shared/references/content-schema.md — every block type and its fields.
• ../../shared/assets/example-deepdive.json — a worked fictional example.