1---2name: article-research3description: >-4 Researches a B2B SaaS article topic that has passed topic-precheck: reads what the top results actually cover,5 builds a coverage matrix of what they all say and what none of them say, pulls the company's own evidence, lists6 the questions buyers ask in their own words, checks every figure against its source, and proposes the one angle7 only this company can write. Returns READY, READY WITH GAPS, COMMODITY or BLOCKED. Use it after topic-precheck8 says GO and before outlining or drafting. Not for choosing the keyword (use keyword-selection) or writing the9 article (use article-write).10license: MIT11compatibility: >-12 Works in Claude, ChatGPT, Codex, Cursor and any agent that reads SKILL.md. Reads the live results and sources if13 the agent can browse; otherwise works from pages and sources the reader pastes. Python 3 is optional, for the14 coverage matrix and source ages.15metadata:16 author: SHAKEUP17 version: "1.0.0"18 stage: get19 plugin: content20 homepage: https://www.shakeuphq.com/skills/article-research21---22 23# Article research24 25Turns a cleared topic into a research brief a writer can use: what ranks already says, what it misses, and the evidence to say something it doesn't.26 27## Purpose28 29- One job: one research brief for one topic, with an angle backed by evidence found in this run.30- Stage: get. It reads data in and structures it; it ends with a readiness verdict for the writer.31- It never fills a gap with invented evidence, a remembered statistic or a source it didn't open. A gap stays a gap, labelled.32 33## Use when / not34 35| Situation | Use |36| --- | --- |37| A topic passed `topic-precheck` (GO, GO (supporting content), or a NEEDS DECISION the reader settled) | this skill |38| Re-researching a topic before a rewrite | this skill, then `article-write` |39| The topic hasn't been prechecked | `topic-precheck` first |40| Auditing a published page against today's results | `refresh-audit` |41| Checking one draft's claims | `claim-check` |42 43## Inputs44 45| Input | Required | Ways to provide, in order | If missing |46| --- | --- | --- | --- |47| The cleared topic | yes | a `topic-precheck` handoff; the reader's request | ask once; without a precheck, say it wasn't run and mark coverage `partial` |48| The top results for the primary keyword | yes | browse them; page text or headings the reader pastes; titles and URLs only | ask the reader to paste the top 5; titles only means matrix cells `not read` and coverage `partial` |49| The company's evidence | no | `## Claims and proof` in the profile; the precheck's evidence list; items the reader pastes | angle can't pass the non-commodity test; likely `COMMODITY` |50| Buyer questions | no | sales or support notes the reader shares; People Also Ask if browsing; community threads; `## Buying moments` | use the profile's moments and objections; coverage `partial` |51| Sources for figures | no | open each one in this run; source text the reader pastes | the figure goes to gaps |52 53## Profile read54 55From `company-profile.md`: `## Company`, `## Product`, `## Buyers` (roles and objections), `## Buying moments`, `## Positioning` (unique attributes), `## Claims and proof` (with `### Never say`), `## Competitors` (mention policy), and every `## Learnings` entry for `article-research`.56 57No profile: ask in one message for the buyer, what the product does, and any first-party proof on this topic. Say that `company-profile` saves this next time.58 59## Steps60 611. **Apply learnings** for this skill (a source marked dead, an angle the reader rejected before).62 632. **Check the precheck.** Read the handoff. `STOP` means `BLOCKED`: don't research a stopped topic unless the reader overrides it (record that as a learning). Carry forward the pillar, the page to avoid overlapping with, the evidence ids and the author.64 653. **Read what ranks.** Follow `references/research-method.md` section 1 for 5 to 7 results. Record format, headings, core argument, data cited and weak spots per page. Say how many pages were read in full and how many were titles only.66 674. **Build the coverage matrix.** Draft 6 to 12 subtopics (method section 2). Run:68 69 ```70 python3 scripts/coverage_matrix.py --input results.json --today <YYYY-MM-DD> [--fast] --ignore "<topic head term>"71 ```72 73 `--ignore` takes the topic's own head terms (they appear on every page, so matching on them marks everything covered). The script matches words, not meaning: read its matrix against the headings, correct any cell it got wrong, and say how many you changed. Without Python, mark each page per subtopic as `section` (a heading covers it), `mention` (the body touches it) or `none`, then class each subtopic: `baseline` if a section in 3 or more of 5 pages (60%: readers expect it), `thin` if mentioned but a section in at most 1, `gap` if no page covers it, `partial` otherwise. A page read as title only is `not read`, never `none`. Say which way you ran it.74 755. **Find the freshest data.** For each claim the article will need, find a source that passes the credibility, recency and verification tests (method section 3). Open each one now. Run `claim-check` on the list, or apply its test inline. A figure that fails goes to gaps with what the source does say. Flag stats in the top pages that newer data replaces.76 776. **Pull the company's evidence.** Map each item from `## Claims and proof`, the precheck list or the reader's paste to a subtopic. Strict relevance: the item must be about that subtopic, not share a word with it. Uncleared quotes and claims under "Claims to confirm" are listed as `needs clearance`, never used.78 797. **Map buyer questions** (method section 4): the questions in the buyer's words, the vocabulary they use, the misconceptions, and which questions deserve their own section.80 818. **Rank differentiation candidates** (method section 5): angle gaps, then depth gaps, then freshness gaps. Each needs evidence found in this run.82 839. **Propose one angle.** One sentence on what this article says that the coverage matrix shows nothing ranking says, and one sentence naming the evidence that lets only this company say it. Apply the non-commodity test: would a careful summary of the top 5 contain it, or could a competitor publish it unchanged? If yes to either, it is not the angle.84 8510. **List E-E-A-T needs** (method section 6): experience, expertise, claims needing citation, and the YMYL flag.86 8711. **Suggest sections** in order: the active intent first, then the passive intents by what the reader needs next. These are suggestions for `article-write`'s outline, not the outline.88 89## Check and verdict90 91| Verdict | Condition (first match wins) |92| --- | --- |93| `BLOCKED` | No topic, the precheck said STOP and the reader didn't override it, or no results could be read at all (not even titles) |94| `COMMODITY` | No candidate in step 8 is backed by evidence found in this run (the company's data, cleared customer words, a documented method or a first-hand finding), so no angle passes the non-commodity test: the article would be a rewrite of what ranks. Stop and route back to `topic-precheck` as a NEEDS DECISION |95| `READY WITH GAPS` | An angle passes the non-commodity test (provisionally, when pages were read as titles only), but some needs are open: pages not read in full, a subtopic with no evidence, a figure that failed verification, or a quote waiting for clearance |96| `READY` | An angle passes the non-commodity test, at least 5 pages were read in full, and every figure in the brief was verified in this run |97 98Named stops: `BLOCKED` asks for the missing input. `COMMODITY` stops and tells the reader what evidence would change it (for example "a cleared customer example of <subtopic>" or "your own data on <figure>"). No other stops; `READY WITH GAPS` hands over with every gap labelled.99 100## Learn101 102Append to `## Learnings` when:103 104- the reader rejects the proposed angle (a `proposal` with their reason, such as "we don't publish anything on pricing");105- a source turns out dead, wrong or paywalled (a `fact` naming the source, so later runs skip it);106- the reader confirms a buyer question from sales or support (a `fact`, so `article-research` and `hook-writer` reuse it).107 108Example: `- 2026-10-24 | article-research | fact | The 2019 attribution survey most top pages cite was replaced by a 2025 edition | Why: both sources opened 2026-10-24 | Status: noted`109 110## Output111 112```113Verdict: <READY | READY WITH GAPS | COMMODITY | BLOCKED> · Coverage: <complete | partial (what's missing)>114Topic: <topic> · Primary keyword: <keyword> · Researched: <date> · Pages read in full: <n> of <n>115 116What ranks117| # | Page | Date | Format | Core argument | Weak spot |118 119Coverage matrix (by <script | reading>)120| Subtopic | Page 1 | Page 2 | Page 3 | Page 4 | Page 5 | Class | Company evidence |121 122Consensus: <what every top page agrees on>123Where they differ: <the split, and which pages hold which side>124 125Freshest data126| Claim | Source | Date | Status (verified, failed, needs text) |127Outdated figures in the top pages: <old figure, page> → <newer figure, source>128 129Company evidence130| Item | Type | Subtopic | Status (usable, needs clearance) |131 132Buyer questions: <questions in their words, most important first>133Vocabulary: they say <x>, not <y>134Misconceptions: <buyers think x; the evidence says y>135 136The angle: <one sentence> · Why only this company: <evidence ids>137Other candidates: <type, one line each>138E-E-A-T needs: experience <...> · expertise <...> · claims to cite <...> · YMYL <yes | no>139Suggested sections: <ordered list>140Gaps: <every open item, labelled>141Learnings applied: <list, or none>142```143 144Then the handoff block.145 146## Hand off147 148```handoff149skill: article-research150version: 1.0.0151verdict: READY WITH GAPS152coverage: partial (2 of 6 pages read as titles only)153for: <topic>154outputs:155 primary_keyword: salesforce attribution reports156 angle: <one sentence>157 angle_evidence: [<claim or item ids>]158 sections: [<suggested sections, in order>]159 verified_sources: [<url>, <url>]160 pillar: <URL or none>161 author: <name, bio URL>162 ymyl: false163next: [article-write]164open: [clearance for the customer quote on <subtopic>]165```166 167For `COMMODITY`, `outputs.angle` is `not available`, `next` is `[topic-precheck]` and `open` names the evidence that would change it.168 169## Failure modes170 171| Problem | Do this |172| --- | --- |173| The agent can't browse and the reader pasted titles only | Build the matrix from what was given, mark cells `not read`, and say the angle is provisional until the pages are read |174| A top result is a forum thread or a video | Record it as audience intelligence and its format; don't use it as a source |175| A competitor's page ranks in the top 5 | Read it like any other; follow `## Competitors` mention policy when the angle contrasts with it |176| The only evidence is a public study | It can support a section but not the angle; the angle needs something first-party |177| The reader's evidence contradicts a top source | Keep both, with sources, and say which the article should lead with and why |178| The topic turns out to be 2 intents | Say so, propose which one this article serves, and suggest the other for `topic-precheck` as its own topic |179 180## Influenced by181 182- Google's guide to optimizing for generative AI features in Search, which separates non-commodity content (unique expert or experienced takes beyond common knowledge) from content that restates what is already available: https://developers.google.com/search/docs/fundamentals/ai-optimization-guide183- SHAKEUP's content engine: the top-5 coverage matrix, evidence held to strict relevance, every source fetched in the same run, and "commodity" treated as a real finding that goes back to the precheck rather than a reason to write anyway.