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

[antoinedc]

Summary

Doc-only follow-up to #1287. Updates .claude/references/MARKETING.md so future sessions/contributors understand the new picker behavior without re-reading the code.

Adds:

• Per-cluster performance multipliers — CLUSTER_PERFORMANCE_MULTIPLIER in config.js, applied in classifyAndScore. Sourced from PostHog 30d sustained-traffic data, refresh quarterly.
• Comparison Listicle as the 6th content type — corrects the previous "5 Content Types" line.
• Listicle cadence override — pickNextTopic force-picks a comparison-listicle every 4 articles from LISTICLE_TOPICS, seeded with node blog/pipeline/seed-listicles.js (idempotent).
• Recency ordering note — pickNextTopic uses frontmatter date: for chronological ordering, not articlePath (slug, no date prefix). Same gotcha Greptile flagged on Bias blog picker toward proven-performing clusters; schedule comparison-listicles every 4 articles #1287.

No code changes. No behavior changes.

Test plan

• Skim the diff
• Confirm the documented behavior matches what landed in Bias blog picker toward proven-performing clusters; schedule comparison-listicles every 4 articles #1287

🧙 Built with WOZCODE

[greptile-apps]

Greptile Summary

This doc-only PR adds four sections to .claude/references/MARKETING.md describing picker behavior said to have landed in #1287, but none of the documented features are present in the codebase: CLUSTER_PERFORMANCE_MULTIPLIER is absent from config.js, comparison-listicle is not in contentTypeOptions, LISTICLE_TOPICS and seed-listicles.js don't exist, and pickNextTopic contains no listicle-cadence or frontmatter-date logic.

• P1 — CLUSTER_PERFORMANCE_MULTIPLIER and per-cluster multiplier logic are not in config.js or classify.js.
• P1 — comparison-listicle content type is not registered; LISTICLE_TOPICS, seed-listicles.js, and the every-4-articles cadence don't exist anywhere.
• P1 — pickNextTopic never reads frontmatter date:; the recency-ordering note documents a non-existent code path.

Confidence Score: 2/5

Not safe to merge — the documentation describes multiple features that don't exist in the codebase, which will mislead future contributors.

Four independent P1 findings: every new section added by this PR documents code (constants, files, logic) that is absent from the actual pipeline implementation. The PR's own test plan asks to confirm the documented behavior matches what landed in #1287, but that check would fail across all four additions.

.claude/references/MARKETING.md — all four new sections document non-existent functionality.

Important Files Changed

Filename	Overview
.claude/references/MARKETING.md	Documentation update describing four features — CLUSTER_PERFORMANCE_MULTIPLIER, comparison-listicle content type, LISTICLE_TOPICS/seed-listicles.js listicle cadence, and frontmatter-based recency ordering — none of which exist in the actual pipeline code (config.js, classify.js, project.js).

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["MARKETING.md documents"] --> B["CLUSTER_PERFORMANCE_MULTIPLIER\nin config.js"]
    A --> C["comparison-listicle\ncontent type"]
    A --> D["LISTICLE_TOPICS + seed-listicles.js\n+ every-4-articles cadence"]
    A --> E["pickNextTopic reads\nfrontmatter date:"]

    B -->|"❌ Does not exist"| F["config.js has no such constant\nclassify.js has no multiplier logic"]
    C -->|"❌ Not registered"| G["contentTypeOptions has 5 keys only\nsuggestContentType never returns it"]
    D -->|"❌ Does not exist"| H["LISTICLE_TOPICS absent from config.js\nseed-listicles.js file missing\npickNextTopic has no cadence override"]
    E -->|"❌ Incorrect"| I["pickNextTopic sorts by score only\nno frontmatter parsing, no articlesSinceListicle"]

Loading

Comments Outside Diff (1)

1. .claude/references/MARKETING.md, line 115 (link)

   pickNextTopic does not read frontmatter date: fields

   The actual implementation in project.js reads project board items via gh project item-list and sorts exclusively by score (line 140). It never touches article frontmatter or counts articlesSinceListicle. Documenting a date: gotcha for a code path that doesn't exist may mislead contributors debugging unrelated ordering issues.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: .claude/references/MARKETING.md
   Line: 115
   
   Comment:
   **`pickNextTopic` does not read frontmatter `date:` fields**
   
   The actual implementation in `project.js` reads project board items via `gh project item-list` and sorts exclusively by `score` (line 140). It never touches article frontmatter or counts `articlesSinceListicle`. Documenting a `date:` gotcha for a code path that doesn't exist may mislead contributors debugging unrelated ordering issues.
   
   How can I resolve this? If you propose a fix, please make it concise.

   

Prompt To Fix All With AI

Fix the following 4 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 4
.claude/references/MARKETING.md:89
**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.

### Issue 2 of 4
.claude/references/MARKETING.md:93
**`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).

### Issue 3 of 4
.claude/references/MARKETING.md:103-113
**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`.

### Issue 4 of 4
.claude/references/MARKETING.md:115
**`pickNextTopic` does not read frontmatter `date:` fields**

The actual implementation in `project.js` reads project board items via `gh project item-list` and sorts exclusively by `score` (line 140). It never touches article frontmatter or counts `articlesSinceListicle`. Documenting a `date:` gotcha for a code path that doesn't exist may mislead contributors debugging unrelated ordering issues.

_{Reviews (1): Last reviewed commit: "docs(marketing): document cluster perfor..." | Re-trigger Greptile}

[greptile-apps]

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.

[greptile-apps]

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.

[greptile-apps]

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.