Content Research Workflow

The research folder is the synthesis layer between keyword discovery, NeuronWriter analysis, and content writing. Research can be performed by a human, AI, or both, but every content item uses the same artifact contract.

Ownership Rules

keyword-research.csv
  owns Keyword ID (KW-######)

content-inventory.csv
  owns content PID (PREFIX-######)

research/<PID>/
  owns the research synthesis for that content item

Keyword research may exist without ever becoming content. Its Target Post PID stays empty until an opportunity is selected. Once an idea is created, the selected keyword row points to the content PID.

Directory Layout

research/
└── DEV-000008/
    ├── research.md
    ├── serp-analysis.md
    ├── brief.md
    └── sources/

The directory is created automatically by scripts/new-idea.py. The command also copies reusable SERP-analysis and content-brief templates into the PID directory. Do not manually assign a PID or create a research directory for a keyword opportunity before the content idea exists.

Create an Idea

cd /home/rezriz/github/seo-content/web-project/id86.net
python3 scripts/new-idea.py \
  --title "Grep Cheatsheet" \
  --category devops \
  --keyword "grep" \
  --keyword-id KW-000001 \
  --type cheatsheet \
  --researcher ai

The command creates the idea row, assigns the next content PID, sets Research Path, links KW-000001 through Target Post PID, and creates research.md, serp-analysis.md, brief.md, and sources/ in one operation. The keyword ID is optional; when supplied, the keyword text must match and an already-linked opportunity is rejected.

For existing manually edited rows, reconcile expected directories with:

python3 scripts/ensure-research-folders.py --dry-run
python3 scripts/ensure-research-folders.py

Research Contract

---
pid: DEV-000008
researcher: human  # human | ai | mixed
status: draft       # draft | complete
keyword: grep
---

Required research sections:

• Keyword summary
• Searcher and intent
• Audience and sophistication
• What the page must answer
• Differentiation / unique angle
• Verified facts and sources
• Cannibalization check
• Recommended outline
• Internal-link targets
• Conversion goal / CTA
• Editorial notes

serp-analysis.md records ranking URLs, SERP features, People Also Ask questions, competitor gaps, and the differentiation angle. brief.md turns that analysis into the writing specification: primary and secondary keywords, outline, entities, examples, links, sources, and schema.

The research file should cite the relevant keyword row and NeuronWriter brief rather than copying their full data. It becomes complete only after source and overlap checks are finished.

Workflow

Keyword discovery
  -> select opportunity
  -> create content idea and PID
  -> create research/<PID>/
  -> human or AI research
  -> NeuronWriter SERP analysis
  -> complete research.md
  -> write content Markdown
  -> NeuronWriter evaluation
  -> fact check and human approval
  -> schedule and publish

NeuronWriter provides topical and SERP guidance. It does not replace fact checking, audience definition, differentiation, internal linking, or editorial judgment.

AI Automation Boundaries

The workflow is designed for a topic-agnostic AI agent, but the agent must not invent missing keyword data or publish unreviewed high-risk claims. Automation is divided into three levels:

Level	Agent may do	Human gate
Automatic	Import and normalize exports, assign KW-######, detect duplicates, validate registers, create research files, run link/frontmatter checks	Supply the source export and credentials
AI with review	Cluster keywords, classify intent, recommend priority/content type, analyze SERPs, create briefs, draft Markdown, suggest links and metadata	Approve keyword selection, mapping, claims, and final draft
Approval required	Schedule or publish new content, change URLs, archive content, handle legal/medical/financial/security-sensitive claims	Explicit human approval before first publication

The recommended trigger is:

source CSV supplied
  -> agent imports and validates
  -> agent proposes keyword/PID mapping
  -> human approves selected opportunities
  -> agent creates research, SERP analysis, and brief
  -> agent drafts and runs QA
  -> human approves the article
  -> scheduled publish automation runs

needs_source is a holding status for a retained opportunity whose exact keyword or intent is unavailable. The agent may report it, but must not infer the missing value. A keyword row alone never creates a content PID.

Publishing, WordPress Post ID recording, and GSC performance collection are integration steps and require their respective scripts, APIs, credentials, or scheduled jobs to be configured. The research workflow itself does not claim that an AI agent can force Google to index a regular page.

Validation

validate-inventory.py checks that populated Research Path values point inside research/, that the PID directory and research.md exist, and that the research frontmatter PID, researcher, and status are valid.

keyword-research.csv is validated separately for exact keywords, controlled search intent, content type, unique Keyword ID values, duplicate keyword/topic/category combinations, and valid Target Post PID links. needs_source is allowed for retained rows whose exact keyword or intent is still being recovered; the validator reports those rows as warnings. Use import-keywords.py for any compatible keyword export, assign-keyword-ids.py for missing IDs, and validate-keyword-research.py before linking opportunities.