Research & Content Optimization (Phase 2)

Goal: understand the searcher's task, decide whether a page should exist, and record the evidence and editorial choices that will guide the brief. Research reduces uncertainty; it does not produce certainty about rankings.

The research folder is the home for research

All research belongs in data/<workspace>/research/<pid>/. That includes manual SERP review, competitor notes, saved sources, AI prompts, and the raw NeuronWriter export. There is no separate research CSV.

scs research --workspace bs --pid FS-0001
scs research --workspace bs --pid FS-0001 --check
scs research --workspace bs --pid FS-0001 --check --require-export

data/<workspace>/research/<pid>/
├── README.md          # question, hypotheses, decision, prompt log
├── serp.md            # top results, H2 matrix, gaps, PAA, differentiation
├── competitors/       # one note per competitor URL
├── sources/           # saved pages, PDFs, citation notes
├── exports/           # nw-2026-11-01.json, spyfu-*.csv, gkp-*.csv
├── prompts/           # prompts used to turn exports into serp.md
└── assets/            # images and diagrams for the article

--require-export fails the check when exports/ is empty. Use it when the brief depends on a tool export.

Using NeuronWriter

NeuronWriter is an input, not a phase. Run the analysis in its dashboard, export the result into exports/, and translate it into the research files and the brief.

NeuronWriter data	Where it goes
Terms per section (title, H1, H2, content_basic)	serp.md H2 matrix and brief §6
Term usage ranges	Brief §9 generation notes — directional guidance only
PAA questions	serp.md → questions_to_answer in front matter
Content questions	Brief §5 outline
Entities	clusters.entity_coverage → entities_to_cover in front matter
Word count target	briefs.word_count → target_words in front matter
Content score	serp.md evidence and README.md
Intent breakdown	keywords.intent — validate against the live SERP

important

NeuronWriter terms are reference guidance only. The final article must prioritize search intent, clarity, information gain, and natural writing over rigid term matching.

Review the SERP, not just the URLs

Review the leading results for the actual query and location/device context that matters to the site. For each useful result, record its page type, intended audience, what it does well, and what it does not answer. Compare recurring topics and formats, but do not copy competitor headings as an outline.

Then decide whether the right action is to create a new page, improve an existing page, consolidate overlapping pages, or not proceed. Record the reason and link to the relevant existing page when applicable. A competitor URL count is a completeness check; it does not prove that the SERP was reviewed well.

The research check

scs research --check requires:

• README.md and serp.md;
• ## Question and ## Decision in README.md;
• ## Top results, ## H2 matrix, ## Gaps, and ## Differentiation in serp.md;
• at least 3 competitor URLs in serp.md (a structural minimum, not a research-quality score);
• no TODO, TBD, [insert, [fill, or lorem ipsum placeholders.

The check verifies that expected files and sections exist and that obvious placeholders were removed. It cannot verify that a SERP was reviewed, that a source supports a claim, or that the proposed page adds value. A human must review those decisions before approving the brief.

Turning research into a brief

When the research supports a clear page decision:

1. Set decision=go in keywords.csv.
2. Plan the cluster role in clusters.csv (kc_type, pillar_pid, entity_coverage).
3. Render the brief with scs brief.
4. Carry relevant SERP evidence, gaps, entities, and reader questions into the brief. State what the page will contribute and what it will deliberately leave to other pages.
5. Approve the brief only after scs brief --check passes.

warning

A research folder is not a substitute for checking the live SERP. The URLs in serp.md must be real results you reviewed, not AI-generated examples.

Next: Content Generation or the Brief Gate.