Engagement Scoring#
Engagement scoring is the mechanism by which better-stale-bot prioritizes Bucket B issues — issues that are potentially stale but not yet labeled — before applying the Stale label. Rather than processing issues in chronological order (as actions/stale does), the bot ranks issues by a weighted engagement score and labels the quietest threads first, giving active discussions more time to resolve naturally .
Formula#
The score is defined in Step 2 of the agent prompt:
engagement_score = (3 × distinct_users) + (2 × total_comments_and_reactions) + (1 × whole_weeks_since_last_updated)
Variable definitions :
| Variable | Definition |
|---|---|
distinct_users | Count of distinct non-bot users who commented or reacted on the issue |
total_comments_and_reactions | Total non-bot comments plus reactions on the issue or its comments |
whole_weeks_since_last_updated | floor(weeks since last update), minimum 0 |
Bot activity is excluded from all three inputs .
Sorting and Tie-Breaking#
Issues are sorted ascending by score — lowest score (quietest thread) is processed first . When two issues share the same score, the one with the earlier last non-bot activity timestamp takes priority .
Auditability Requirement#
Before taking any action on a Bucket B issue (adding a comment or label), the agent must write out the fully substituted arithmetic — e.g., engagement_score = 3 × 1 + 2 × 4 + 0 = 11 — with each term labeled. A bare final number is not accepted . This produces an auditable trail in the workflow run log.
Context: Where Scoring Fits#
Engagement scoring only applies to Job (a) of each run (labeling potentially stale issues). Job (b), which handles already-stale issues, does not use the score — it simply checks whether the grace period (days-before-close) has elapsed with no qualifying activity .
Processing stops before exceeding the safe-output caps compiled into frontmatter max: fields, so the sorted order determines which issues get processed within a single run .
Primary Sources#
.github/workflows/better-stale-bot.md— Step 2, lines 76–94 — canonical formula, variable definitions, sorting rules, and auditability requirement- Migration guide — Processing Order — contrast with
actions/stalechronological ordering
