Engagement Platform Hybrid Area Implementation Plan

Plans1.305 words7 min read

active

Execution note: Use executing-plans to implement this plan task-by-task.

Goal: Establish a unified Engagement Platform documentation area under UX Design using a hybrid model (central governance + module-level implementation).

Architecture: Create a new docs/Shared/Shared Capabilities/Engagement Platform/ hub with canonical governance docs for leaderboard, achievements, rewards, event contracts, module responsibilities, and phased rollout. Keep existing module docs as implementation sources and avoid disruptive edits to already-changing files.

Tech Stack: Markdown docs, repository naming conventions, lightweight CLI verification (find, rg, git status).

Task 1: Create engagement area scaffold

Files:

Step 1: Draft docs with shared format

Use consistent sections: Purpose, Scope, Logic, Dependencies, Change log.

Step 2: Ensure hybrid decision is explicit

Record why not monolithic-only and not fully split-only.

Step 3: Validate file creation

Run: find "docs/Shared/Shared Capabilities/Engagement Platform" -maxdepth 1 -type f | sort
Expected: 3 files listed.

Task 2: Define governance contracts

Files:

Step 1: Normalize rules and anti-abuse policies

Define canonical keys and cross-module boundaries.

Step 2: Address known model conflict

Resolve vocabulary-local metaphor vs social global points/level with coexistence policy.

Step 3: Validate critical terms

Run: rg -n "ruleVersion|anti-cheat|lifetime|spendable|event" "docs/Shared/Shared Capabilities/Engagement Platform"
Expected: terms present in governance docs.

Task 3: Add long-term optimization path

Files:

Create: docs/Shared/Shared Capabilities/Engagement Platform/ENG_07_Roadmap_and_Quality_Gates.md

Step 1: Define phased rollout

Phase 1 baseline alignment, Phase 2 consolidation, Phase 3 optimization loop.

Step 2: Define quality rubric + hard gates

Include correctness and safety gates that cannot be overridden by aggregate score.

Step 3: Verify and summarize

Run: git status --short -- "docs/Shared/Shared Capabilities/Engagement Platform" "docs/plans/2026-03-04-engagement-platform-hybrid-area.md"
Expected: only new files from this scope.

Task 4: Add operating and measurement completeness

Files:

Step 1: Complete long-term measurement model

Define north-star, driver, and guardrail metrics to avoid vanity optimization.

Step 2: Add change-control and incident operation model

Define cadence, RACI baseline, rule-change lifecycle, and release checklist.

Step 3: Verify map coherence

Run: rg -n "ENG_08|ENG_09|Metric|Experiment|Change Control|Incident" "docs/Shared/Shared Capabilities/Engagement Platform"
Expected: overview and roadmap reference the two new docs and key policies are present.

Task 5: Establish cross-area current-state baseline

Files:

Step 1: Audit engagement mechanisms across core areas

Home, Practice, Learning, Course, Social, Vocabulary, Register/Account, Payment, Product Discovery decisions.

Step 2: Consolidate inventory with maturity and inconsistency flags

Summarize existing mechanics, ownership, maturity, and key cross-area mismatches.

Step 3: Verify baseline availability

Run: rg -n "Mechanism Inventory|Cross-area|Inconsistencies|Maturity Summary" "docs/Shared/Shared Capabilities/Engagement Platform/ENG_10_Cross_Area_Current_Mechanism_Inventory.md"
Expected: inventory, inconsistency list, and maturity summary are present.

Task 6: Simplification-first completion and stale-content cleanup

Files:

Step 1: Lock minimal UX direction

Add simple-by-default principle and keep/simplify/defer/cleanup decisions.

Step 2: Remove outdated contradictions

Align privacy default and notification-cap precedence across Social/Vocabulary docs.

Step 3: Verify cleanup

Run: rg -n "Simple-by-default|keep/simplify|Platform override|default private|governor" "docs/Shared/Shared Capabilities/Engagement Platform" "docs/Domains/DOL Academy/UX Design/Social" "docs/Domains/DOL English/UX Design/Vocabulary Management/Vocab v2/Engagement Logic/VOCV2_Notification_Rules.md"
Expected: simplification direction and conflict cleanup statements are present.

Task 7: Define practice leaderboard axis + global score model

Files:

Step 1: Lock scoring baseline

Define axis leaderboard (duration | volume | score) and global points formula with qualification gates.

Step 2: Keep UX simple

Home shows only global points teaser.
Detailed axis ranks remain in Practice surface.

Step 3: Verify consistency

Run: rg -n "global_points|axis_type|Practice Points|qualified_activity_count|duration | volume | score" "docs/Shared/Shared Capabilities/Engagement Platform"
Expected: governance, event contract, roadmap, and overview are aligned to the same model.

Task 8: Complete comprehensive achievement + reward + batch operating model

Files:

Step 1: Lock canonical architecture

Define full domain model, taxonomy, achievement->badge->reward chain, idempotency keys, and batch job families.

Step 2: Add long-term reliability controls

Specify orchestration defaults, state transitions, reconciliation policy, anti-abuse gates, and SLO baseline.

Step 3: Enforce anti-drift documentation contract

Set ENG_12 as single source for ABR+Batch and align governance/roadmap docs to this source.

Step 4: Verify integrated completeness

Run: rg -n "Source of Truth|award_key|grant_key|reconciliation|SLO|Batch orchestration|state machine" "docs/Shared/Shared Capabilities/Engagement Platform"
Expected: canonical model, reliability controls, and anti-drift policy are consistently present.

Task 9: Build cross-module point conversion (Practice + Vocabulary)

Files:

Step 1: Define point-conversion architecture

Preserve module-local semantics (PracticePoints, SRS vocab metrics) and add a global conversion layer (learning_points).

Step 2: Lock conversion formulas and safety gates

Define eligibility thresholds, weighted conversion, reward mapping caps, anti-farm rules, and tie-break order.

Step 3: Align contracts and governance

Add required event family for vocab/global conversion and update roadmap/reward governance references.

Step 4: Verify coherence

Run: rg -n "learning_points|vocab_care_points|PracticePointsWeek|VocabCarePointsWeek|RewardEarnedWeek" "docs/Shared/Shared Capabilities/Engagement Platform"
Expected: formulas, events, leaderboard policy, and reward mapping remain consistent across docs.

Task 10: Build vocabulary achievement/badge/reward mechanism

Files:

Step 1: Define vocab achievements

Cover list actions (save/create), first-study milestones, word-count tiers, and list-completion tiers.

Step 2: Define reward and anti-abuse

Add idempotent reward grants, weekly cap, uniqueness rules, and moderation/anti-farm gates.

Step 3: Align event instrumentation

Add required event names and payload fields for vocab achievements and reward grants.

Step 4: Verify consistency

Run: rg -n "vocab_achievement|vocab_list_saved_event|completed_lists_count|vocab_achievement_reward_cap_week|ENG_14" "docs/Shared/Shared Capabilities/Engagement Platform" "docs/Domains/DOL English/UX Design/Vocabulary Management/Vocab v2/Business Logic/VOCV2_Analytics.md"
Expected: achievement tiers, reward caps, and event instrumentation are aligned across docs.