Skip to content

feat(gamification): align indicators engine with Sept 18 Vanishing Badges specification - #73

Merged
lucas-matw-unq merged 2 commits into
mainfrom
feat/update-indicators-sept18
Sep 27, 2026
Merged

lucas-matw-unq merged 2 commits into
mainfrom
feat/update-indicators-sept18

Conversation

@lucas-matw-unq

Copy link
Copy Markdown
Collaborator

Summary

Updates the adaptive gamification indicators engine to align with the revised Vanishing Badges specification (Sept 18, 2026), matching the updated simulator logic and removing obsolete indicator models.

Key Changes

  • Indicators Replaced:
    • Replaced $ET_b$ (estimated time to award), $PMI$ / $relPMI$ (player motivation indicators), and $CMI$ (community motivation indicator) with the new definitions:
      • Def 3.1 Achievable Badges ($AB(p)$): Badges where player has earned all prerequisites and hasn't earned the badge yet.
      • Def 3.2 Individual Badge Interest ($i_3(p, b)$): Time elapsed since badge became achievable: $i_3(p, b) = 1 / (\text{asOfDate} - t_0(p, b))$.
      • Def 3.3 Player Ignored Badges ($\text{ignored_by}(p)$): Achievable badges with interest below the player's median interest across achievable badges.
      • Def 3.4 Community Ignored Indicator ($CII(b)$): Fraction of eligible players ignoring the badge: $|{p \in ep(b) : b \in \text{ignored_by}(p)}| / |ep(b)|$.
  • Section 4.1 Trigger Evaluation:
    • Evaluates whether $\frac{\sum_{p \in P} |\text{ignored_by}(p)|}{\sum_{p \in P} |AB(p)|} \ge \text{threshold}$ (default 0.20, configurable via query parameter).
  • Section 4.2.1 Candidate Selection:
    • Filters candidates to active badges that are not community-ignored ($CII(b) < 0.50$ when $ep(b) \ne \emptyset$).
    • Selects the candidate badge with the minimum $CII(b)$ score (adaptation candidate).
  • DTOs & Controller:
    • Removed obsolete query parameters startDate and daysPerPeriod. Added optional threshold query param.
    • Updated CommunityIndicatorsResponseDto and BadgeIndicatorDto to expose full mathematical trace (isTriggered, triggerBadges, candidateBadges, lowestCII, adaptationCandidateBadge, achievableBadges, ignoredBadges, individualInterest).
  • Documentation:
    • Updated docs/adaptive-gamification/indicators-engine.md with the new definitions, formulas, workflows, and response payloads.
  • Tests:
    • Updated unit tests across strategy, service, and controller; all 57 suites (466 tests) pass.

Refs: #22

…dges specification

- Update IndicatorFormulaStrategy to compute achievable badges AB(p), ignored badges ignored_by(p), individual interest i_3(p, b), and community ignored indicator CII(b)
- Remove obsolete indicators: estimated award time ET_b, player motivation PMI/relPMI, community motivation CMI, and engagement period calculations
- Implement Section 4.1 adaptation trigger (totalPlayerIgnored / allPlayerBadges >= threshold) and Section 4.2.1 candidate badge selection (active, not community ignored, minimum CII)
- Update GetIndicatorsQueryDto with threshold parameter (default 0.20) and CommunityIndicatorsResponseDto to expose full mathematical trace
- Update unit tests and documentation to reflect the Sept 18 specification
@lucas-matw-unq
lucas-matw-unq merged commit e28dc12 into main Sep 27, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant