GetGud Tracker — DEVELOPMENT NOTES
===================================

Current guild beta:
v0.10.3


GROUP TELEMETRY — IMPLEMENTED IN v0.10.3
========================================

Why it exists
-------------
WoW 12.1 can restrict/secret party and raid combat information during content
such as Mythic+ and raid encounters.

GetGud therefore must NOT infer:

  "No Lust event visible"

as:

  "The group did not Lust."

v0.10.3 uses cooperative GetGud telemetry instead.


What is shared
--------------
Each GetGud client shares only events already known trustworthily from its OWN
player:

- combat potion
- pre-pot attached to a pull
- player-cast Bloodlust / Heroism / Time Warp equivalents
- player-used drums

No rotation, DPS, chat, arbitrary combat logs, aura tables, or secret
party-member values are transmitted.


Protocol
--------
Addon prefix:
  GetGudTracker

Protocol:
  1

Message types:
  R = run presence / coverage
  E = compact potion/Lust event chunk

Event messages contain at most four special-use events and stay under WoW's
255-byte addon-message size limit.


Restricted combat / queueing
----------------------------
C_ChatInfo.SendAddonMessage can return AddOnMessageLockdown during restricted
combat.

GetGud does not attempt to bypass that.

Instead:
1. telemetry is queued on the saved run
2. the queue survives /reload
3. GetGud retries after combat, encounter end, or M+ completion
4. AddonMessageThrottle results schedule a delayed retry instead of spamming

Traffic is intentionally small and event-driven.


Coverage is mandatory
---------------------
Example:

  Telemetry 2/5 players

means:
- two players supplied trustworthy GetGud telemetry
- three players are UNKNOWN

It does NOT mean the other players failed to potion or Lust.

Missing telemetry must never become a negative claim.


Run matching
------------
Internal GetGud run IDs are not assumed to match between clients.

Received telemetry is matched using public run context:

M+:
- ChallengeMode map ID
- keystone level
- run start server timestamp

LFG / LFR:
- LFG dungeon ID
- active run context

Normal instances:
- physical instance ID
- active run context

Repeated runs are separated with the stored server-start timestamp.


Pull matching
-------------
Messages include:
- pull start server timestamp
- encounter ID when available
- event time relative to sender pull start

Boss events:
- encounter ID + pull-start proximity

Trash events:
- pull-start proximity

This is intentionally conservative.

If testing reveals ambiguous trash assignment, prefer displaying a marker only
at RUN scope rather than confidently assigning it to the wrong pack.


Persistence
-----------
run.telemetry stores:
- participants
- group-size snapshot
- merged local/remote events
- unsent outbound queue
- outbound de-duplication/send state

This allows M+ telemetry queues to survive /reload.


User control
------------
General -> Group Telemetry

Default:
  Enabled

Disabling:
- stops processing/sending telemetry
- discards unsent outbound messages immediately

Re-enabling:
- announces presence for the current run again


Performance
-----------
No polling and no per-frame telemetry work.

Telemetry runs only on:
- report completion
- run/group events
- addon-message receipt
- a retry timer when server-throttled


STILL NOT IMPLEMENTED
=====================

Buff Lane
---------
Desired visual context:
- Bloodlust / Heroism / Time Warp
- Power Infusion
- personal steroid windows
- racials
- allowed proc/buff windows

This should use Blizzard-supported aura-display mechanisms.

Visual aura display and report analytics are separate problems.


Non-GetGud group Lust detection
-------------------------------
GetGud may later inspect party/raid spellcast information only when Blizzard
returns ordinary readable/non-secret values.

That should remain opportunistic bonus data.

It must never become the foundation of report truth.


Cooldown context
----------------
Future reports may add:
- major personal cooldown timestamps
- cooldown use by trash/boss segment
- cooldown holds before bosses
- session-level cooldown patterns

Good:
  Pillar was held on Trash Pack 7.
  Pack ended at 14:22.
  Boss combat began 7.4 seconds later.

Bad:
  You should have pressed Pillar.

GetGud provides evidence. It should not invent strategic intent.


Phases
------
Universal automatic boss phase detection is still not reliable enough to fake.

Potential future sources:
- encounter-specific modules
- supported boss-mod integration
- explicit trustworthy encounter markers


PRODUCT PRINCIPLE
=================
GetGud should prefer:

  UNKNOWN

over:

  CONFIDENTLY WRONG.

The addon analyzes execution.
It does not play the game for the user.

Press buttons. Find gaps. Get better.
