Buzz Score Epic Breakdown

Buzz Score: Epic Breakdown

Status: Draft for breakdown session Created: 2026-08-18 Last Updated: 2026-08-18 Related Work: Buzz Score epic brief v1.1 - EVO-4333 - EVO-4361 to EVO-4369 - EVO-4125

Purpose

Phase 1 cut into stories, with dependency order and the open product item each one is blocked on.

Estimates are indicative starting points, not commitments. They assume one backend engineer familiar with the gamification and metrics subsystems and exclude review and QA. Size them properly with the people who will do the work.

Sequencing

text

  BS-15 spike ......................................... informs BS-9
  (do first, 1d, no deps)

  BS-1        BS-2         BS-3 Action ----+
  config ---> core ---+--> (open item 3)   |
  3d          3d      |                    |
                      +--> BS-4 Resonance -+--> BS-6 -----+--> BS-7 ---> BS-8 ---> BS-14
                      |    (open item 2)   |    snapshot  |    cron      events    FE wiring
                      |                    |    2d        |    2d        2d        1d
  EVO-4361..4364 -----+--> BS-5 Intention -+              |
  Brand Hub, in PR    |    (open items 4,5)               +--> BS-9 ---> BS-13
                      |                                   |    API       Arti tool
                      |                                   |    3d        2d
                      |                                   |
                      +--> BS-10 ------> BS-11            +--> BS-12
                           harness       replay                Arti rollup
                           3d            2d                    3d

                           \____ no API dependency ____/

Three things fall out of this shape:

BS-1 and BS-2 gate everything. Nothing else can start meaningfully until config and the pure core exist. They are also the two smallest stories with the least uncertainty, so this is a good place for the epic to start rather than a bottleneck to work around.
BS-10, the validation harness, does not wait for the API. It runs the core directly. That means the parameter tuning pass can happen in parallel with API and frontend work rather than after it, which is the difference between tuning before launch and tuning after.
BS-15 should run first, before BS-9 hardens the contract. It is a one-day spike, and its whole value is being cheap and early.

Stories

BS-1: `BuzzScoreConfig` model, service, and admin surface

AC1, AC7. Approximately 3 days. No blockers.

DB-backed versioned parameter record with exactly one active version, a 60 second cached accessor with an invalidation hook, and an admin surface for edits. Follow models/FeatureFlag.js plus services/featureFlagService.js, which already solve this exact problem in this repo.

Not a constants file. AC1 wants a single shared source and AC7 wants changes without a deploy, which together rule out services/gamification/constants/.

Done when: a parameter can be changed and take effect without a deploy, and every version is retrievable by number.

BS-2: Scoring core

AC1, AC2. Approximately 3 days. Depends on BS-1.

Pure functions of (signals, config): the cadence curve, the three slice composers, and the top-level composition with weight renormalization. No database access, no clock reads, no module-scope constant imports.

Includes the invariant fixtures from buzz-score-validation-harness.md, in particular the published cadence tables and the jump-that-holds and spike-then-crash pair.

Note for the story description: services/gamification/helpers/velocityHelper.js already computes a 0-100 composite from posting and release cadence and must not be reused. It is linear, caps at 150%, applies per-level aggressionMultipliers, weights login frequency, and returns { score: 0 } on error. Every one of those is explicitly prohibited by AC2 or the null rule. Its two fetchers are fine; its scoring is the thing being replaced. Say this in the ticket or it will be rediscovered the expensive way.

Done when: the published tables reproduce exactly and all nine invariants pass.

BS-3: Action slice collectors

AC2. Approximately 3 days. Depends on BS-2. Blocked in part by open item 3.

Rolling 28-day posts per week from ScheduledPost.platformStatus.<p>.publishedAt, and rolling 90-day releases per month from Release.release_date. Both wrap the existing velocityHelper fetchers in null-returning variants, because both currently swallow errors into 0.

taskFollowThrough carries 15% of the slice and has no ratio definition anywhere. It also has no clean data path: Task.js has no completedAt, so completion time comes from statusHistory[].changedAt, and ActivityLog has no {userId, activityDate} index.

Two ways to unblock, and the ticket should name both:

Define the ratio and add the index. Adds roughly 1 day.
Set its weight to 0 for Phase 1. Content and release renormalize automatically through the AC1 machinery, at no extra cost. Action at the sweet spot then reads 85.1 rather than swinging between 72.4 and 87.4 on an undefined signal.

Done when: posts and releases produce correct rolling rates including externally-created posts, and a collector failure yields null rather than 0.

BS-4: Resonance slice collectors and math

AC3. Approximately 5 days. Depends on BS-2. Blocked by open item 2.

Weekly series per metric per platform out of MetricPoint through repositories/socialMetricsRepository.js, then growth, consistency, and base-size scaling per sub-signal, with the coverage threshold and per-platform renormalization.

Reuse calculateGrowthRate from helpers/growthTrackHelper.js. It already implements the null-versus-zero convention correctly and carries MIN_PERCENTAGE_BASELINE = 10 for count metrics. Apply that floor to follower counts and not to rate metrics such as Engagement Rate, per the warning in that file.

The consistency term is the open question. AC3 asks for a variance penalty and separately requires that a jump which holds must score, and a variance penalty cannot do both. The ticket should carry the simulation from buzz-score-feasibility.md item 2 and be explicit that fixture 1 is the acceptance test.

Scope note: “streams” in Phase 1 means account-level Spotify Listeners. Per-track stream history is not persisted, and YouTube does not exist as an integration at all.

Done when: all four Resonance invariants pass and a disconnected platform renormalizes rather than zeroing.

BS-5: Intention slice, coverage and recency

AC4. Approximately 5 days. Depends on BS-2 and on EVO-4361 to EVO-4364 merging. Blocked by open items 4 and 5.

A facet coverage calculator over the six Brand Hub documents, using services/brand-hub/emptyDocs.js as the canonical field map, plus the recency multiplier off BrandHubDocument.updatedAt.

Three things the ticket must carry:

There is no completeness notion today. isSeeded is a boolean and is true for a completely empty seed. This is built from scratch.
content is Schema.Types.Mixed, so shapes are convention rather than schema. The scorer owns a canonical facet-path map and reads defensively.
Seeded entries must be excluded. seedFromBuzz writes exactly three taste-timeline entries and one decision-log entry for every questionnaire completer, and EVO-4364 backfills the same for existing users. A naive “does this document have entries” facet therefore passes automatically for the entire alpha cohort and measures nothing. lastUpdatedBy: 'seed', seededAt, and each entry’s source all make seeded material identifiable.

Done when: an all-empty seeded Brand Hub scores near 0 on coverage rather than passing the append-only facets, and the recency curve matches the parameter registry table.

BS-6: `BuzzScoreSnapshot` model and persistence

AC6. Approximately 2 days. Depends on BS-3, BS-4, BS-5.

One document per user per day carrying the composite, three slices with status, every sub-signal with value-or-null and reason, overTargetRatio, coverage counts, and configVersion.

Follow the MetricPoint meta convention, and heed the lesson recorded in that model: do not pass timeseries: { granularity: 'days' }, which is not a valid MongoDB value and silently degrades to an ordinary collection. Declare an ordinary collection deliberately. No TTL, for the reasons recorded on PostMetricPoint.

Done when: a snapshot round-trips with nulls and reasons intact, and configVersion is always populated.

BS-7: `BuzzScoreScheduler`

AC6. Approximately 2 days. Depends on BS-6.

extends BaseCronService, registered in services/cron/index.js, at 0 23 * * * UTC so it runs after the metrics crons settle. The last of those is instagram-engagement-notify at 20 22 * * *.

Overlap protection, timeout, per-job logging, and the cross-instance run lock through models/CronJobRunClaim.js all come from the base class. Recompute must be idempotent: rerunning for the same day overwrites that day’s snapshot.

Done when: a full cohort run completes inside its timeout and a second run for the same day produces an identical snapshot.

BS-8: Change detection and downstream events

AC6. Approximately 2 days. Depends on BS-7.

AC6 requires that a sub-signal moving materially while the composite does not must be detectable downstream. Compare each sub-signal against the previous snapshot and emit through eventsHub/eventEmitter.js when a configured delta is crossed.

The threshold is a config parameter, not a literal.

Done when: a sub-signal move with a flat composite produces an event.

BS-9: API endpoint, feature flag, contract test

AC1, AC5. Approximately 3 days. Depends on BS-6. Informed by BS-15.

GET /api/v1/buzz-factory/v2/buzz-score on the existing router, standard envelope, catchAsync and AppError, gated by requireFlag with a key in enums/flagKey.js and a seed row in seeds/featureFlags.js. Full shape in buzz-score-contract.md.

A pure read. The precedent to avoid is in this same subsystem: getBuzzFactoryOverviewV2Service promotes users and fires notifications from inside a GET.

Contract test covering the five shape-changing cases, following docs/UI_CONTRACT_TESTING.md. Note that “no snapshot yet” returns 200 with null slices, not 404. A new artist is not an error.

Done when: all five contract cases pass and the flag gates cleanly in both states.

BS-10: Validation harness

AC7. Approximately 3 days. Depends on BS-2. Does not depend on the API.

Script under scripts/ that loads a config version or an overrides file, resolves a cohort, runs the same scoring core the nightly job runs, and writes per-artist, distribution, and coverage outputs. Read-only; it must never write snapshots.

Requires --asOf support in the collectors, which is what makes historical replay work.

Done when: Jacob and John can change a parameter, rerun, and read a distribution without an engineer in the loop.

BS-11: Historical replay and seeding

AC6, AC7. Approximately 2 days. Depends on BS-10.

Backfill snapshots over historical MetricPoint data so trajectory exists at launch rather than accumulating from zero.

Label backfilled snapshots honestly. They are the formula applied retroactively, not measurements taken on those days. The Intention slice in particular cannot be replayed accurately, because Brand Hub history only goes back to when BrandHubWriteLog shipped on 2026-08-12.

Done when: replayed snapshots are distinguishable from live ones.

BS-12: Arti rollup branch and formatter

AC5. Approximately 3 days. Depends on BS-6. Repo: both.

Extend services/agent/smartRollupBuzzFactoryService.js to carry the score block. On the Python side, add the branch in generate_initial_rollup_stream() and a typed formatter in app/services/user_data_insights/data_formatter_service.py, so follow-up turns stop falling through to the generic formatter.

Voice constraint, and this is the substance of the story rather than a footnote. The existing buzz_factory rollup prompt opens with “Celebration”, asks for “genuine enthusiasm”, and instructs the model to “make them feel proud”. The Buzz Score register is the opposite by design: a falling score is a diagnosis rather than a scolding, no participation points, and the ability to tell an artist to do less of something. These cannot share a prompt.

Done when: a score with a dash in it is explained as “we cannot see this” rather than as a deficiency.

BS-13: Arti on-demand tool

AC5. Approximately 2 days. Depends on BS-9. Repo: genesis-train.

A BUZZ_TOOLS module on the app/agents/questionnaire/tools.py template, registered in CHAT_TOOLS and announced in both catalogues in app/services/ai/prompt_service.py. Calls the API through APIClient._make_request with the user’s JWT from state["token"].

Done when: “why is my buzz score 62” returns an explanation grounded in the actual breakdown.

BS-14: Frontend analytics wiring

AC6. Approximately 1 day. Depends on BS-8. Repo: artistevolve-fe.

Replace the hardcoded values at components/common/components/BuzzfactoryInfo.tsx lines 30 and 38 and at app/(dashboard)/dashboard/page.tsx:821, each of which currently sends buzz_score: 0 and user_level: 1, and wire the real score into the PostHog events that lib/analytics/trackers/gamification-tracker.ts already defines: buzz_score_updated with old_buzz_score and new_buzz_score, and buzz_score_milestone.

The tracker is already built. This is wiring, not new instrumentation.

BS-15: EVO-4125 contract reconciliation

AC5. Approximately 1 day, spike. No dependencies. Do this first.

EVO-4125 is in PR and renders level progress as a placeholder. The real contract is three slices with per-slice status and an inspectable breakdown, not a single number, and level progress is an explicit non-input under AC2. So the eventual swap changes what the gauge means rather than repointing a data source.

Settle whether the gauge’s props match the AC1 shape before it hardens.

Done when: the gauge’s contract is agreed against buzz-score-contract.md, or a follow-up is raised.

Decision gates

Each open item blocks a specific story. None blocks starting the epic.

Open item	Blocks	If unresolved at sprint start
1. 60 versus 70 cap	UI copy, not code	Ship with the locked 0.30 weight. Hold copy referencing a cap.
2. Resonance consistency term	BS-4	Implement the retention factor. It satisfies both AC3 clauses; a variance penalty does not.
3. `taskFollowThrough` definition	BS-3	Set weight to `0` and renormalize. Reversible through config alone.
4. P15, unapproved brand material	BS-5	Count only what reached the document. The narrower reading is the reversible one.
5. Seed-entry exclusion	BS-5	Exclude via `lastUpdatedBy: 'seed'`. Not excluding makes the facet measure nothing.

Every fallback in the right-hand column is reversible through config or a small change. None of them require guessing at something expensive to undo.

Explicitly out of Phase 1

From the brief, recorded here so they do not creep in at breakdown: geometric Intention (distillation, embeddings, tightness, specificity, trajectory), uniqueness and cross-artist comparison, LLM-judged content quality, L6 gating on Buzz, score projection, and external output analysis.

Testing conventions

Layer	Approach	Template
Scoring core	Plain unit tests, no mocks	any pure helper test
Collectors	`jest.unstable_mockModule`, then dynamic `await import()`	`__tests__/smartRollupBuzzFactoryService.test.js`
Snapshot and scheduler	`mongodb-memory-server`, mocking only side-effecting collaborators	`__tests__/buzzFactoryOverviewV2.test.js`
Config service	Mock-only, covering cache expiry and version stamping	`__tests__/featureFlagService.test.js`
API	Contract test	`__tests__/contracts/instagramOverview.contract.test.js`
genesis-train	`AsyncMock` on `APIClient._make_request`	`app/tests/unit/test_buzz_factory_rollup.py`

Jest runs ESM through NODE_OPTIONS=--experimental-vm-modules; utils/logger.js is mocked in every unit test.