Download the skill ↓

then paste it into Claude, or save it as SKILL.md

Inside the skill

information-gain-research/SKILL.md

---
name: "information-gain-research"
description: "Research what the top-ranking pages miss for a content brief: recent sources from the last 30 days, a STORM-style fact-check from five grounded perspectives, contradictions, positions, screenshots and original assets, checked by a gate script before the writer gets it."
---

# Information Gain Research (your site)

> **Shared from the growthvibes.ai content pipeline.** [How the whole pipeline works](https://growthvibes.ai/resources/how-i-built-an-seo-content-automation/). This is the skill we run, with our IDs, keys and private details taken out. Anything in angle brackets (`<like this>`) is yours to fill in. It is built to run unattended: it never asks questions, it decides and writes its assumptions down.

## What you need

- A brief from `seo-content-brief` or `thought-leadership-brief` (it reads the brief's outline, gaps and research plan).
- **Firecrawl**: the MCP plus `FIRECRAWL_API_KEY` in `.env` for the bundled scripts. Node 18 or newer, and `npm install sharp` for screenshots.
- **ScrapeCreators** (optional): `SCRAPECREATORS_API_KEY` in `.env` for recent Reddit, X, TikTok and YouTube posts. About 20 credits per article. `GITHUB_TOKEN` is optional.
- **Notion MCP** for the Briefs database, Positions log and Experience bank.
- **Optional:** the `content-library` skill and your CMS connector.
- Bundled scripts (in `scripts/`): `recency.mjs` (the last-30-days step), `check-research.mjs` (the gate before "ready"), `capture.mjs` (screenshots of public pages).

## Fill in before the first run

- Database ids, wherever placeholders appear.
- Your credit caps, if ours (Firecrawl credits per article type) do not suit you.


Sits between the brief and the writer. The brief says what the SERP already covers. This skill finds what nobody covers yet, checks it, takes positions, and builds original assets, so the article adds something that doesn't exist in the top 10.

Runs unattended in Claude Code on the author's computer. **Never ask questions.** Decide, log it under Assumptions, continue.

**Scope:** the brief is the instruction. Never change the keyword, slug, cluster or outline. New ideas are proposed additions with a placement in the outline.

## The chain (in this order, on purpose)

Information gain is worked as two things, **recent** and **fact-checked from different angles**. That is a working rule for us, not Google's definition, so never write it into an article as if Google said it.

1. **Gaps** (Phase 2): what the top 10 misses.
2. **Step A, recent** (Phase 2b): what was said and shipped in the last 30 days, with dates.
3. **Gap research** (Phase 3) and **verification** (Phase 4).
4. **Step B, fact-check** (Phase 4b): the STORM pass over everything found so far. It can downgrade or drop Step A's claims.
5. **Positions** (Phase 5), **screenshots and assets** (Phase 6), **output** (Phase 7).

## Config

| Setting | Value |
|---|---|
| Site | `your site`, articles at `/resources/` |
| Author | the author |
| Sanity | project `<your Sanity project id>`, dataset `production`, types `post`, `caseStudy`, `service` |
| Notion Briefs | data source `<your Notion data source>` |
| Notion Positions log | data source `<your Notion data source>` |
| Notion Experience bank | data source `<your Notion data source>` (tool notes, see Phase 1) |
| Recency window | 30 days (the brief may set 90 for slow topics) |
| Max gaps | 5 |
| Raw working files | `work/<slug>/` (git-ignored). Screenshots go in `work/<slug>/assets/` |

**Firecrawl cost, measured:** a search is 2 credits, a scrape 1, a full-page screenshot 1. **Never use the `query` format on a scrape: it costs 5 credits.** Use markdown (1 credit) and read it yourself. Hacker News and GitHub through `recency.mjs` cost nothing.

**Credit cap by article type** (log the cap, the credits used and the image count in the run log):

| Article type | Cap | Screenshots |
|---|---|---|
| explainer, comparison of concepts, default | 30 | up to 3, only where they prove a point |
| tutorial | 25 + 2 per captured step, max 60 | one per key step (up to 10) |
| listicle, service roundup | 20 + 7 per subject, max 90 | 2 to 3 per subject: the home or product page (required), pricing, one feature screen |
| tool review | 45 | 4 to 6 |
| comparison (X vs Y) | 20 + 5 per tool, max 50 | the same page types for each tool |

**The cap is soft.** The hard cap is 1.5 times the cap. **Budget is never a reason to drop a brief gap, an FAQ question or a criterion while you are under the hard cap.** Cover them. Waste is what runs a cap out (the 5-credit `query` format, scraping pages you already have), so don't waste.

## Where things live (results in Notion; raw working files in git-ignored `work/<slug>/`)

Each brief page in the Briefs database has two child pages:

- **Brief data:** written by the brief skill. Outline, keywords, FAQs, gaps with research questions, the coverage map, `article_type`, `subjects` and `research_plan`
- **Research:** written by this skill. Summary on top, research JSON below. Screenshots stay as local files (below), the page lists them

**Working folder:** use the `work/<slug>/` folder the runner names in its prompt (its slug comes from the calendar keyword). Run without the runner, use the brief's slug.

Also write the same JSON to **`work/<slug>/research.json`**: it is what `check-research.mjs` checks, and the writer's run can read it.

Positions go in the **Positions log** database, shared across all articles.

Notion API limits to respect: 2,000 characters per text object (split long text and JSON into chunks), 1,000 blocks and 500 KB per request, 180 requests per minute.

## Placeholder pages

Some posts in Sanity are unfinished templates. Never use a placeholder post as evidence, own experience, or a link target.

A post is a placeholder if any of these are true:

- its body starts with "Placeholder article"
- it contains template lines such as "Explain the problem and who it is for", "First step", "Second step" or "Close with a takeaway"
- its body has under 150 words of real text

Service pages and case studies are fine to use when their text is real.

## Status values

- `ready`: every gap researched with sourced evidence and `check-research.mjs` passes
- `low_confidence`: some gaps have thin or single-source evidence, or fewer than 3 perspectives could be sourced; reasons listed
- `budget_exhausted`: credit cap hit, remaining gaps listed
- `blocked`: no Brief data found, reason given

## Thought leadership briefs

If Brief data has `track: "thought_leadership"`, the brief came from an idea and an inspiration URL, not a keyword. Run the same chain with these differences:

- **Coverage map = the inspiration's sections.** Don't search for or scrape ranking pages. The brief's `competitors` list is empty, and that is expected.
- **Capture the visual plan.** Phase 6 runs on the brief's `visual_plan`: for every entry of kind `screenshot` or `evidence`, find the public page that shows what the reader must see (the vendor's docs page for a settings screen, a changelog, a README, the study), capture it with `capture.mjs`, crop to the relevant area and annotate it for steps (boxes, numbered circles, arrows). Public pages only; logged-in screens cannot be captured, so look for the docs or a guide that shows them. For build-in-public briefs, also use any screenshot the author put in `work/build-logs/assets/<log-name>/` (look at each; skip one showing a key, ID or personal address; record it as an asset with `credit: "your site"`). Entries of kind `own` are built by the writer. A section with no capturable source: note `no_capture_reason` and leave it to the writer's own image.
- **Smaller budget.** Use the lower of the article-type cap and 20 credits unless a subject needs captures (screenshots follow the article type as usual).
- **Gaps come from the brief** (unverified claims, missing numbers, limits, "does it still work"). Verify each claim the inspiration makes that the article will repeat: find the primary source (docs, changelog, repo) and date it.
- **Recent step (Phase 2b) is central** for news and tool content: official changelogs, release notes, GitHub and Hacker News first.
- **Experience bank and Positions log lead** in Phase 1: match the brief's `experience_to_use` and `positions_to_use`, and tag tool notes as usual.
- The inspiration URL goes into `inspiration_sources` with `used_for`, so the writer credits it.
- **Build-in-public briefs** (`build_in_public: true`): the build log named in the brief is the primary source and counts as `own_experience`. Don't re-research what the log already states. Research only what the article adds around it: external sources and docs for each tool (current pricing, limits, changelog, dated), the methods or videos the build credits (verify they exist and say what the log says they say), and outside viewpoints for the STORM pass. Mark every tool in the log `tested_by_george: true`. Keep the do-not-disclose list out of the research JSON. Never invent results, traffic or costs: if the log says UNKNOWN, it stays unknown.

## Phase 0: Inputs

Pick up briefs with Status `Brief ready`. Read the **Brief data** child page and take as is:

- primary and secondary keywords, slug, outline, audience, intent
- `article_type`, `subjects` (the tools, agencies or steps to cover, with their page URLs) and `research_plan` (perspectives, recency target, **criteria**, visual plan)
- gaps (🔵 items) and their research questions
- coverage map, SERP list and citable sources already found

No Brief data: status `blocked`, stop.
Gaps without research questions: write 1 to 3 specific questions per gap and log it.
No `research_plan` (an older brief): build one from the rules in the brief skill (default perspectives, a 30-day recency target) and log it under Assumptions.

## Phase 1: Load what's already known (0 credits)

1. Use the coverage map from Brief data as the record of what competitors cover. Don't rescrape competitor pages. Scrape one only to check a specific claim (1 credit, counts toward the cap).
2. Query the author's own material in Sanity: published posts, case studies and services related to the topic. Skip placeholders. This is the only allowed source for first-hand experience.
3. Query the Positions log for Active positions on this topic and related topics.
4. **Tool notes.** For every subject that is a named tool or company, query the Experience bank for rows whose `Name` starts with "Tool note:" or whose `Company or context` is that tool. These are what makes own experience with a named tool solid (what the author did, what happened, when). Put each match in the entity's `experience_note_url` and set `tested_by_george: true`. No note: `tested_by_george: false`; the writer may still use own experience on occasion and otherwise grounds the tool in other ways.
5. Search the content library (0 Firecrawl credits) for the topic and for each brief research question: `node <content-library skill>/scripts/search.mjs "<question>" --limit 10`. It returns chunks and idea cards with source title, author, URL and date. If the command fails (missing keys, no network), log it under Assumptions and carry on without the library.

## Phase 2: Confirm and find gaps

Check every brief gap against the coverage map. Drop a gap if 2 or more pages actually cover it, and log why.

Then look for more:

- **Missing:** questions the audience would ask that no page answers
- **Shallow:** topics mentioned in passing but never explained
- **Outdated:** prices, features, stats or dates that look stale. Check the current value at the source
- **Contradictions:** two ranking pages that disagree. Find out which is right
- **Unbacked claims:** numbers with no source, or a source that doesn't say what's claimed
- **No original asset:** a comparison, calculation or table nobody has built

Rank by value to the reader and fit with the outline. Keep the top 5.

## Phase 2b: Step A, what is recent

One command per topic and per subject that matters (the brief's recency target says which):

```
node scripts/recency.mjs "<query>" --days 30 --web --social --github owner/repo --comments 2 --out work/<slug>/recency-<n>.json
```

`--social` adds Reddit, X, TikTok and YouTube through ScrapeCreators (the key is `SCRAPECREATORS_API_KEY` in `.env`). Use it for the main topic. For each subject of a list, review or comparison use `--reddit --youtube` (or whichever platforms matter) to keep the cost down. `--balance` prints the credits left.

- It covers **Hacker News** (stories with points, plus the top-level comments of the most discussed ones, which are real questions and real wording), **GitHub releases and the most discussed new issues** for repos you name (use it for open-source tools: n8n, Claude Code and the like), **Google results filtered to the period** (2 Firecrawl credits), and with `--social` **Reddit posts and their top comments, X posts, TikTok videos and YouTube videos** (1 ScrapeCreators credit per request, so one topic with `--social --comments 2` is about 6).
- The output lists `covers` and `doesNotCover`. Copy them into `recency.covers` and `recency.does_not_cover` and state them on the Research page. It never covers Instagram or LinkedIn. **X search is Google-indexed and not time-filtered**, so it mostly returns older posts and usually leaves nothing inside the window: do not count on X for what is recent. Reddit, TikTok and YouTube are filtered to the period. If the ScrapeCreators key is missing or a platform call fails, the output says so in `notes`: the recent step still runs on the rest, and the reliability read says what was missing.
- **ScrapeCreators budget:** about 20 requests per article, up to 40 for lists and roundups. Log the number used. The free tier is 1,000 credits.
- Social posts are opinions, not facts. A claim taken from a post is `verified: true` only when a primary source confirms it. Comments are for real questions, complaints and vocabulary: paraphrase, never quote a stranger by name.
- Items with `needsDateCheck: true` have no date. Scrape the page (1 credit) to find the date, or drop the item. Never call an undated item recent.
- Official changelogs, release notes and pricing pages are the best recent sources for tools. Scrape them directly and take the date from the page.
- Keep what is dated inside the window and relevant to a gap or an outline heading. Each kept item goes in `recency.items` with its outline heading, the claim in your own words, the source URL, the date, the platform, the engagement and `verified`.
- Nothing recent found: say so in `recency.none_found_reason`. Don't pad.
- Comments feed headings and the FAQ: real questions, real complaints, real wording.

## Phase 3: Research each gap

Per gap: one Firecrawl search (limit 10, no scraping, 2 credits), then scrape 2 to 3 sources (1 credit each, basic). When the right source is obvious (an official pricing page, a known press release), scrape it directly and skip the search. Run gaps in parallel.

Source priority:

1. the author's own material from Sanity, placeholders excluded (0 credits)
2. The content library: other people's ideas that aren't on Google (0 credits). Use the ideas, not the wording. Credit the author and link the URL where one exists. Library findings go in the research JSON like any other, with `library: true` and the source title and author. Extra care with `newsletter` sources: paraphrase only, never quote
3. Primary sources: official docs, pricing pages, changelogs, original studies, government data
4. Practitioner sources: GitHub issues, Hacker News, product communities. Firecrawl doesn't scrape Reddit or LinkedIn, skip them
5. Adjacent-topic articles, for angles only

Rules:

- Skip domains already in the SERP
- Track credits from every call. Stop at the cap and set `budget_exhausted`
- Failed scrape: note once, move on

### Criteria for every subject

For a list, review, roundup or comparison, each subject is researched against the same `research_plan.criteria` (best for, pricing, where it breaks, who should skip it, and whatever else the brief lists, such as export and lock-in). One markdown scrape of the subject's docs, product or pricing page usually answers most of them (1 credit). A criterion still open after one search gets `not_found_reason` with the query tried; it is never silently left out. Every FAQ question about a property of the subjects is a criterion.

**Every gap in the brief and every FAQ question is researched, or dropped with a reason that is not budget.** List them all in `brief_gaps`.

## Phase 4: Verify

- Every fact gets a source URL and a short supporting excerpt
- Every number is checked against its source. Calculations are done in code from sourced inputs
- A claim citing another source is checked at the original. Can't reach it: mark unverified and leave it out
- Sources disagree: keep both, say which is more current or primary
- Date-stamp prices and anything that changes

One source only: `low_confidence`, unless it's primary.

## Phase 4b: Step B, the STORM fact-check

Works on what Phases 2b to 4 retrieved. The five perspectives are **grounded in retrieved sources**, never role-play: a perspective whose evidence URL was not retrieved is dropped, not invented. The perspectives share the searches already run, they are not five new research runs. Use the brief's `research_plan.perspectives` to decide which of the five matter and what each is asked; if fewer than three can be sourced, the status is `low_confidence`.

0. **Research frame.** One sentence with the question this article answers and one **verification sub-claim**: the claim in the brief or the SERP that everything rests on, which this pass tests (for example "the three plans compared are still priced as the top guides say"). The frame goes at the top of the Research page with the verdict on the sub-claim (confirmed, partly, not confirmed) once the pass is done.
1. **Perspectives.** Practitioner (people who use it), academic (studies, primary data), skeptic (complaints, failures, reviews), economist (cost, pricing model, incentives), historian (what changed and why). Per perspective: the core position in two sentences, the strongest evidence with its source URL, and the one thing only that perspective would say.
2. **Contradiction map.** Where perspectives or sources clash, which side has the stronger evidence, and the one question that would settle the biggest clash. List what they all agree on (likely true, safe to state) and what none addressed (the blind spots, candidates for the new angle).
3. **Synthesis.** A one-paragraph summary, the five findings ranked by reliability, a connection nobody else has drawn, one actionable insight, one open question.
4. **Peer review.** Score each finding 1 to 10 for confidence, with the reason. Name the weakest link, check for bias in the sources, name the missing perspective, give an overall grade (A to F) and a verdict.

Rules for this step:

- **It can overrule Step A.** A recent claim that fails the check is dropped or marked `verified: false` and goes into `unverified_claims`.
- Every finding scored **below 6** goes into `unverified_claims`, with the finding text copied **exactly** as it is in `peer_review.findings` (the check matches the text). The writer leaves those out.
- Contradictions are content: state each with its heading, the sides, the stronger side and why. The writer takes a position on them.
- Tag every contradiction, recency item and entity with the outline heading it belongs to.

## Phase 5: Take positions

For each gap and each important contradiction, take the position the article should hold. Check the Positions log first.

- **Matches an Active position:** reuse it, link to it. Don't create a duplicate. Stay consistent across articles
- **Contradicts an Active position:** only change it if the new evidence is stronger and more current. Set the old one to `Revised`, add a line to its Evidence explaining why, create the new one
- **New:** create it in the Positions log

Each position:

- **Position:** one clear sentence
- **Why:** the evidence, with sources
- **Against:** the strongest counterpoint and why the position still holds
- **Confidence:** High, Medium or Low, taken from the peer review score (8 and above High, 6 to 7 Medium, below 6 it is not a position, it is an unverified claim). Low means the writer hedges the wording

No position without at least one verified source. Positions log fields: Position, Topic, Evidence, Sources, Confidence, First used in (the article's target URL), Status `Active`.

## Phase 6: Original assets and screenshots

Build what doesn't exist in the SERP:

- comparison tables from primary data
- calculations (cost, time, ROI) done in code, inputs and sources shown. Label any usage figures that aren't sourced as an example
- checklists or frameworks synthesized from the research
- **screenshots**, by article type (see the table in Config for the budget)

### Screenshots

Capture **more than the pricing page**: for every subject take the home or product page (required) and the pricing page, and a feature or product screen where one is public. The writer picks the one that shows each tool best, so give it a choice. Public pages only: never a logged-in view, anything with personal data, or people's faces. The tool refuses local, private and account-looking URLs. Everything is a **local file** in `work/<slug>/assets/`: the writer uploads it to Sanity from there. (Firecrawl's image links expire, so never store those.)

1. **One fetch per page.** `node scripts/capture.mjs fetch <url> work/<slug>/assets <name>` writes `<name>.raw.png` (the whole page, 1 credit) and prints its real pixel size.
2. **Look at it.** `node scripts/capture.mjs slice work/<slug>/assets/<name>.raw.png <n>` writes band n (1080 px tall) and prints the pixel range it covers. Open it with the Read tool. **Crop coordinates are in the original raw pixels** printed by `fetch` and `slice`, not in whatever a viewer displays: take the band's `y` and add the position inside the band.
3. **Make each image.** `node scripts/capture.mjs make <raw.png> work/<slug>/assets/<name>-<what>.png --crop x,y,w,h --alt "what it shows"`. Take as many crops as needed from the same raw file. Crop to the relevant area, never a full page. For tutorials add `--annotate spec.json` (boxes, numbered circles, arrows in the cropped image's pixels) so the reader sees where to look. The tool resizes, adds the owl watermark and keeps the file under 5 MB. It writes `<name>.json` with the source URL, capture date and credit.
4. **Record it** on the entity in the research JSON: `file`, `alt`, `credit`, `creditUrl`, `capturedAt`, `kind` (`home`, `pricing`, `ui`, `step`).
5. A page that blocks capture, or a shot that would mislead: say so in the run log and use a different page. Never mock one up and never use a generated image where a real capture is possible. If a site's terms forbid screenshots, skip it and say so.
6. Date every capture. The writer shows the date in the credit, and UIs change.

**Evidence screenshots (every article type).** Besides the subject pages, capture the proof for the strongest claims while you research: the passage of a study, a chart in someone's post, a changelog entry, a pricing change, a thread, an official statement. When a finding supports a claim in the outline and a picture of the source would make it more credible than a sentence, capture it with the same tool (`fetch`, `slice`, `make`), cropped to the relevant passage and never the whole page, and attach it to the finding as `asset`: `file`, `alt`, `credit` (the author or site, since it is their content), `creditUrl` (the page), `capturedAt`, `kind` `evidence`, and `claim` (the sentence it backs). Not every finding: about 2 to 6 in a long article, none if nothing needs it. Public pages only, no personal data or faces, 1 credit each and inside the credit cap. The writer shows them with a visible "Source:" line and decides which to use.

**Entities** are the brief's `subjects` (each with its `criteria` filled in): for a listicle, roundup, review or comparison, one entry per tool or agency (home, pricing and docs URLs, dated facts with sources, captures); for a tutorial, one entry per key step with a capture. Run the chain per entity, not once for the whole article: a recent check (changelog, pricing change, complaints), and the STORM perspectives that matter for it (practitioner = users, skeptic = reviews and complaints, economist = pricing model).

## Phase 7: Output

Create the **Research** child page under the brief page. If a Research page already exists, replace its content instead of creating a second one.

**Top, for the author, in this order:**
1. **Research frame and verdict, then bottom line up front:** two or three sentences on what the article can say that the top 10 can't.
2. **Reliability read:** the peer review grade, the weakest link, how many perspectives were sourced, and what the recent step covered and did not cover.
3. A short summary per section: gap, position, 2 to 3 key findings with links, assets.
4. **Contradictions and blind spots.**
5. **Recent items** with dates.
6. **Screenshots:** a list with local path, what it shows, source, capture date.
7. Flags: placeholders skipped, claims not to use, dropped gaps, perspectives dropped for lack of sources.

**Bottom, for the writer:** the research JSON in code blocks, split into chunks of 2,000 characters max, labeled "Part X of Y". Every finding, recency item, contradiction and asset is tagged with the outline heading it belongs to, so the writer can load one section at a time.

```json
{
  "status": "ready",
  "status_reasons": [],
  "slug": "",
  "primary_keyword": "",
  "article_type": "listicle | tool_review | comparison | tutorial | service_roundup | explainer",
  "criteria": ["best for", "pricing", "where it breaks", "skip it if"],
  "brief_gaps": [{"title": "", "status": "researched | dropped", "reason": ""}],
  "brief_notion_url": "",
  "credits": {"cap": 0, "hard_cap": 0, "used": 0},
  "sections": [
    {
      "heading": "exact outline heading, or proposed new H2/H3",
      "parent": "parent H2 if this is an H3, else null",
      "is_new_section": false,
      "gaps": [
        {
          "title": "",
          "type": "missing | shallow | outdated | contradiction | unbacked | no_asset",
          "why_new": "what the top 10 says or misses",
          "findings": [{"fact": "", "source_url": "", "excerpt": "", "date": "", "verified": true, "library": false, "source_title": "", "source_author": "", "asset": {"file": "", "alt": "", "credit": "", "creditUrl": "", "capturedAt": "", "kind": "evidence", "claim": ""}}],
          "position": {"statement": "", "why": "", "against": "", "confidence": "High", "positions_log_url": ""},
          "own_experience": [{"fact": "", "sanity_url": ""}]
        }
      ],
      "assets": [{"type": "table | calculation | checklist", "title": "", "data": {}, "caption": "", "sources": []}]
    }
  ],
  "recency": {
    "window_days": 30,
    "covers": ["hacker-news", "github", "google (time-filtered)"],
    "does_not_cover": ["reddit posts", "x", "tiktok", "instagram"],
    "none_found_reason": "",
    "items": [{"heading": "", "claim": "", "source_url": "", "date": "YYYY-MM-DD", "platform": "", "engagement": "", "verified": true}]
  },
  "research_frame": {"question": "", "verification_claim": "", "verdict": "confirmed | partly | not_confirmed"},
  "perspectives": [{"role": "practitioner | academic | skeptic | economist | historian", "heading": "", "position": "", "evidence": [{"fact": "", "source_url": ""}], "unique_insight": ""}],
  "contradictions": [{"heading": "", "between": ["", ""], "claims": ["", ""], "stronger_side": "", "resolving_question": ""}],
  "consensus": [""],
  "blind_spots": [""],
  "synthesis": {"summary": "", "ranked_findings": [{"finding": "", "reliability": 8}], "hidden_connection": "", "actionable_insight": "", "frontier_question": ""},
  "peer_review": {"findings": [{"finding": "", "confidence_1_to_10": 0, "reason": ""}], "weakest_link": "", "bias_check": "", "missing_perspective": "", "grade": "", "verdict": ""},
  "entities": [
    {
      "name": "", "kind": "tool | agency | step", "heading": "",
      "urls": {"home": "", "pricing": "", "docs": ""},
      "facts": [{"fact": "", "source_url": "", "date": ""}],
      "criteria": [{"criterion": "", "value": "", "source_url": "", "date": "", "not_found_reason": ""}],
      "assets": [{"file": "work/<slug>/assets/<name>.png", "kind": "home | pricing | ui | step", "alt": "", "credit": "", "creditUrl": "", "capturedAt": "YYYY-MM-DD"}],
      "no_capture_reason": "",
      "tested_by_george": false,
      "experience_note_url": ""
    }
  ],
  "inspiration_sources": [{"url": "", "used_for": ""}],
  "dropped_gaps": [{"title": "", "reason": ""}],
  "unverified_claims": [],
  "assumptions": [],
  "writer_rules": []
}
```

**Before setting the status:** save the JSON to `work/<slug>/research.json` and run `node scripts/check-research.mjs work/<slug>/research.json`. Fix every error (usually a perspective without a retrieved source, an undated recent item, or a low-scored finding missing from `unverified_claims`). Only a passing check allows `ready`. Then set the brief's Status to `Research ready`.

## Writer handoff rules (included in the JSON)

- Label new value in the text, e.g. "none of the top guides cover this"
- Recent facts carry their date in the sentence. State each contradiction as a contradiction and take the side the evidence supports
- Link every source used. Paraphrase and cite, short quotes only, never copy wording
- Library findings are other people's work: use the idea, credit the author by name with a link where one exists, never paste their wording
- First-hand experience: use `own_experience` (Sanity) and the Experience bank first; the writer may add anonymous first-person stories (see the article-writer skill)
- For named tools the writer grounds each tool differently (own experience, someone told me, what people say, judged from the page) and never invents a result, number or quote. Tool notes make own experience solid: `tested_by_george` is true where one exists
- The writer must use the STORM output: at least three perspectives heard, each contradiction stated with a side taken, a blind spot as the new angle, the TL;DR in the order of the ranked findings
- **`writer_rules` is for facts only** (dates, unverified claims, contradictions, what to hedge). Never put rules in it about how the writer talks about tools or uses first-person experience, and never write "ground the tools in the pricing page and say so": that is decided in the article-writer skill and overrides anything here
- Never use anything in `unverified_claims`
- Medium and Low confidence positions get hedged wording
- Example calculations are labeled as examples, not benchmarks

## Rules

1. Never ask. Decide, log, continue.
2. Never change the brief's keyword, slug, cluster or outline. Additions are proposals with a placement.
3. Never invent facts, numbers, quotes, perspectives or experience. Every claim has a verified source, and every perspective has retrieved evidence.
4. Never use placeholder posts as evidence, experience or links.
5. Sources the competitors didn't use come first. Information gain is the job.
6. Respect the credit cap for the article type. Track credits from every call.
7. Positions follow evidence and stay consistent with the Positions log.
8. Notion is the store for the results. One Research page per brief, never duplicates. Screenshots are local files in `work/<slug>/assets/`.
9. Say plainly what the recent step covered and what it did not.
10. Plain language, no em dashes, no filler.
11. One status per run, and `ready` only when `check-research.mjs` passes.
12. Every brief gap, FAQ question and criterion is covered for every subject, or has a reason that is not budget.

The step that gives an article something the top 10 doesn’t have. It runs after a brief and does two things in a fixed order: find what is recent, then fact-check it from different angles. It’s the heaviest step of my content automation and the one I’d keep if I had to throw the rest away.

What it does

  • Confirms the brief’s gaps and finds more: missing, shallow, outdated, contradictory, unsourced
  • Finds what changed in the last 30 days on Hacker News, GitHub, time-filtered Google and (optionally) Reddit, X, TikTok and YouTube
  • Checks every number at its source and dates anything that changes
  • Runs a STORM-style pass: practitioner, academic, skeptic, economist and historian views, each built on retrieved sources, a contradiction map and a peer review
  • Takes positions consistent with your positions log
  • Captures and annotates screenshots of public pages, then runs a gate script before marking the research ready

What you need

  • A brief from the SEO brief or the thought leadership brief
  • Claude Code, Node 18 or newer and npm install sharp (for screenshots)
  • Firecrawl: the MCP plus FIRECRAWL_API_KEY in .env
  • Optional: SCRAPECREATORS_API_KEY for social posts (about 20 credits per article) and GITHUB_TOKEN
  • Notion MCP for the brief, positions log and experience bank

How it works

  1. Gaps. Checked against what competitors already cover.
  2. Recent. scripts/recency.mjs collects dated items from the last 30 days. Undated items are not “recent”.
  3. Research and verify. Your own material and library first, then primary sources, then practitioners.
  4. STORM fact-check. Five perspectives, each grounded in a retrieved source, then contradictions, synthesis and a 1 to 10 peer review. Anything under 6 is never used.
  5. Positions and assets. Sides taken, tables and calculations in code, screenshots via scripts/capture.mjs.
  6. Gate. scripts/check-research.mjs must pass before the status can be “ready”.

Try asking

  • “Research the brief for ai seo tools.”
  • “Run information gain research on this brief and tell me what the top 10 misses.”

Install it

  1. Download the ZIP above.
  2. Claude Code: unzip it into .claude/skills/ in your project (or ~/.claude/skills/ for all projects). Keep the folder name; the scripts folder goes with it.
  3. Add the keys from “What you need” to a .env file in your project, and connect the MCP servers it uses.
  4. Claude.ai: upload the ZIP under Settings, Capabilities, Skills. The instructions work there too; the scripts need Claude Code.

It’s part of a pipeline: topical map, SEO brief or thought leadership brief, research, writer (and review writer), inbound links, with the content library as memory. The skill is above; it’s plain Markdown, so change anything you like.

Questions

How do I install it in Claude Code?

Download the ZIP and unzip it into .claude/skills/ inside your project (or ~/.claude/skills/ for every project). Keep the folder name. The scripts folder inside it travels with the skill.

Can I use it in Claude.ai?

You can upload the ZIP under Settings, Capabilities, Skills, but the bundled scripts need a terminal, so Claude Code is the better home. The instructions still work in Claude.ai with the same connectors.

Is anything private left in it?

No. Our IDs, keys, database links and private details were removed. Anything in angle brackets is a placeholder for your own setup.

Want one built for your stack?

Book a 30-minute call. We’ll map where AI can take growth work off your plate, and what to build first.

Book a strategy call →psst… cameras optional ✦