Skip to content

docs(marketing): document blog picker performance bias and comparison-listicle conventions #1288

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
antoinedc wants to merge 1 commit into
base: develop
Choose a base branch
from
Open

docs(marketing): document blog picker performance bias and comparison-listicle conventions #1288

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 9 additions & 1 deletion .claude/references/MARKETING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,9 +87,11 @@ Collects from 5 sources, classifies into 12 topic clusters, scores, creates GitH

**Scoring weights:** EIP=3, ERC=3, ethresearch=2, arxiv=2, magicians=1, Google Trends=0.5. Threshold: 5 pts.

Copy link
Copy Markdown

@greptile-apps greptile-apps Bot May 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Documented constant does not exist in config.js

CLUSTER_PERFORMANCE_MULTIPLIER is not defined anywhere in blog/pipeline/config.js or anywhere else in the repo. Similarly, classifyAndScore in classify.js contains no per-cluster multiplier logic — it scores purely with WEIGHTS constants. A contributor following this doc to "update the constants" after refreshing PostHog data will find nothing to update.

Prompt To Fix With AI 
This is a comment left during a code review.
Path: .claude/references/MARKETING.md
Line: 89

Comment:
**Documented constant does not exist in `config.js`**

`CLUSTER_PERFORMANCE_MULTIPLIER` is not defined anywhere in `blog/pipeline/config.js` or anywhere else in the repo. Similarly, `classifyAndScore` in `classify.js` contains no per-cluster multiplier logic — it scores purely with `WEIGHTS` constants. A contributor following this doc to "update the constants" after refreshing PostHog data will find nothing to update.

How can I resolve this? If you propose a fix, please make it concise.

Fix in Claude Code

**Per-cluster performance multipliers** (`CLUSTER_PERFORMANCE_MULTIPLIER` in `config.js`, applied in `classifyAndScore`): boost top performers (account-abstraction, security-auditing, evm-internals at 1.3-1.5x) and dampen underperformers (ai-agents-onchain 0.7x, zk-cryptography 0.6x). Derived from PostHog 30d sustained-traffic data. **Refresh quarterly** by re-running the analysis and updating the constants.

**12 Topic Clusters:** AI Agents Onchain, Account Abstraction, Encrypted Mempools & Privacy, Payments & Streams, Security & Auditing, L2 & Rollups, ZK & Cryptography, DeFi Primitives, NFT & Token Standards, EVM Internals, Protocol & Networking, Governance & Standards.

Copy link
Copy Markdown

@greptile-apps greptile-apps Bot May 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 comparison-listicle content type is not registered in config.js

PROJECT.contentTypeOptions in config.js has exactly 5 keys (erc-tutorial, eip-explainer, research-deep-dive, upgrade-guide, trend-survey) — comparison-listicle is absent. suggestContentType in classify.js never returns that value either. Any card the picker tries to set with this type will silently skip the field assignment (see setProjectFields — it no-ops when contentTypeOptionId is falsy).

Prompt To Fix With AI 
This is a comment left during a code review.
Path: .claude/references/MARKETING.md
Line: 93

Comment:
**`comparison-listicle` content type is not registered in `config.js`**

`PROJECT.contentTypeOptions` in `config.js` has exactly 5 keys (`erc-tutorial`, `eip-explainer`, `research-deep-dive`, `upgrade-guide`, `trend-survey`) — `comparison-listicle` is absent. `suggestContentType` in `classify.js` never returns that value either. Any card the picker tries to set with this type will silently skip the field assignment (see `setProjectFields` — it no-ops when `contentTypeOptionId` is falsy).

How can I resolve this? If you propose a fix, please make it concise.

Fix in Claude Code

**5 Content Types:** ERC Tutorial, EIP Explainer, Research Deep Dive, Upgrade Guide, Trend Survey.
**6 Content Types:** ERC Tutorial, EIP Explainer, Research Deep Dive, Upgrade Guide, Trend Survey, **Comparison Listicle** (the highest-converting format — best-X-for-Y-in-2026 style).

**GitHub Projects V2 Board:**
- Project ID: `PVT_kwDOBLpTN84BRc80` (org: `tryethernal`, number: 1)
Expand All @@ -101,6 +103,12 @@ Collects from 5 sources, classifies into 12 topic clusters, scores, creates GitH

Picks the highest-scoring "Detected" card (round-robin by cluster), runs 3-phase Claude pipeline, generates images, publishes directly to develop. No manual review step.

**Listicle cadence override** (`pickNextTopic` in `project.js`): every 4 articles, force-pick the highest-scoring `comparison-listicle` from Detected/Backlog if any exist. Listicles outperform other formats ~3x but the trend scan doesn't generate them — they come from `LISTICLE_TOPICS` in `config.js`, seeded onto the project board via `node blog/pipeline/seed-listicles.js`.

**Adding a new listicle topic:** append to `LISTICLE_TOPICS` (title, cluster, score, body brief), run `node blog/pipeline/seed-listicles.js` (idempotent — skips existing titles). The picker will surface it on its next listicle-cadence trigger.

**Recency ordering:** `pickNextTopic` reads `date:` from each Published article's frontmatter to count `articlesSinceListicle` correctly. Don't try to use `articlePath` for ordering — it's a slug, not date-prefixed.

**Execution flow:**
1. `git pull` latest develop
Comment on lines 103 to 113
Copy link
Copy Markdown

@greptile-apps greptile-apps Bot May 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Listicle cadence, LISTICLE_TOPICS, and seed-listicles.js do not exist

Three things documented here are absent from the codebase: (1) LISTICLE_TOPICS is not defined in config.js; (2) blog/pipeline/seed-listicles.js does not exist; (3) pickNextTopic in project.js has no listicle-cadence override, no articlesSinceListicle counter, and no force-pick logic — it simply returns the highest-scoring Detected/Backlog card sorted by score. Running node blog/pipeline/seed-listicles.js as instructed will throw MODULE_NOT_FOUND.

Prompt To Fix With AI 
This is a comment left during a code review.
Path: .claude/references/MARKETING.md
Line: 103-113

Comment:
**Listicle cadence, `LISTICLE_TOPICS`, and `seed-listicles.js` do not exist**

Three things documented here are absent from the codebase: (1) `LISTICLE_TOPICS` is not defined in `config.js`; (2) `blog/pipeline/seed-listicles.js` does not exist; (3) `pickNextTopic` in `project.js` has no listicle-cadence override, no `articlesSinceListicle` counter, and no force-pick logic — it simply returns the highest-scoring Detected/Backlog card sorted by score. Running `node blog/pipeline/seed-listicles.js` as instructed will throw `MODULE_NOT_FOUND`.

How can I resolve this? If you propose a fix, please make it concise.

Fix in Claude Code

2. `node index.js --pick` → selects topic (skips clusters with active Researched cards)
Expand Down
Loading