# GH3 New Features Scope

## Purpose

This document tracks the planned feature work so the project stays focused, avoids accidental bloat, and keeps implementation choices aligned with Blizzard UI restrictions.

This file is intentionally opinionated. It records what we want to build, what we do not want to build, and the constraints that must stay true even if a tempting feature appears later.

## Guiding Principles

- Keep GH3 officer-friendly, not kitchen-sink.
- Prefer small, composable workflows over large automation systems.
- Keep new features inside existing panes when possible instead of growing the sidebar.
- Store only what is needed for the current workflow.
- Bound all history, caches, and temporary state by age or count.
- Avoid protected-action and taint-heavy patterns.
- Never design around in-combat execution for guild-management actions.

## Confirmed UI Direction

### Maintenance Pane Tabs

The Maintenance pane is the home for the next wave of officer tools.

Tabs:
- Clean-up
- Invites

Why:
- This creates room for more functionality without spending another sidebar slot.
- It keeps officer-only tools grouped together.
- It lowers navigation sprawl and keeps the main UI simpler.

## Feature Goals

### 1. Clean-up Tab

Keep and continue improving:
- Stale member review.
- Pending purge review.
- Exclusions and protected members.
- Lightweight note-tag protection for members who should never appear in kick review.
- Clear action queue with pagination.
- Safer explanations for why a member appears in the queue.
- A Blizzard-safe launch path from the Guild and Communities UI for cleanup actions that must stay close to roster permissions and roster context.

Potential future improvements:
- Better filters for queue type.
- Bulk selection with explicit confirmation.
- Export of current review set.
- Additional guardrails around purge actions.
- A dedicated GH3 Clean-up button on the Guild and Communities roster UI that opens a GH3-styled popup for cleanup review and macro-assisted batch actions.

Do not add:
- Fully automatic deletion without review.
- In-combat cleanup actions.
- Large audit-history retention for every cleanup action.
- Direct batch-kick loops that try to bypass Blizzard protected-action rules.
- Cleanup flows that only work from the GH3 main window when Blizzard requires roster-adjacent interaction.

#### Cleanup Protection Tags

Keep:
- A simple reserved note tag that prevents a member from being included in the kick-candidate scan.
- Tag parsing that works from the existing structured member note field instead of adding a second exclusion store for the same intent.
- Manual exclusions alongside note tags for officers who want both temporary and persistent protection paths.

Do not add:
- Complex tag vocabularies for v1.
- Hidden tag rewrites during scans.
- Separate long-lived audit logs for tag-based skips.

#### Guild And Communities UI Integration

Keep:
- A GH3 Clean-up button attached to the Guild and Communities roster UI.
- A GH3 popup window launched from that button for cleanup review, queue filtering, and batch-prep actions.
- Current roster context when the popup opens so the cleanup view matches the live guild-management surface.
- Macro-assisted or click-driven handoff for protected actions such as repeated kicks.

Do not add:
- Hidden protected actions firing in the background.
- Batch guild actions executed in one automatic loop.
- In-combat UI injection or button rebuilding.
- Cleanup behavior that depends on users suppressing Blizzard warnings.

### 2. Invites Tab

This should start as an officer-facing recruitment and invite workflow, not as a full prospect-hunting system.

#### Phase 1: Build First

##### Applicants

Keep:
- A list of guild applicants or request-to-join candidates.
- Clear online or offline visibility when available.
- Basic review details needed to decide whether to invite.
- Simple action flow from review to invite.

Do not add:
- Complex applicant scoring.
- Large historical archives of every applicant interaction.
- Overengineered sorting or multi-pane recruiter dashboards.

##### Pending Invites

Keep:
- A clear list of players already invited but not yet joined.
- A way to prevent duplicate follow-up.
- Lightweight status indicators when information is available.

Do not add:
- Aggressive polling loops.
- Long-lived status archives.
- Redundant duplicate tracking in multiple tables.

##### Invite Message

Keep:
- One primary saved invite message.
- Optional follow-up message text.
- A preview or clear read-only confirmation of what will be sent.

Do not add:
- Large template libraries in v1.
- Multi-page message editors.
- Complex branching message rules.

##### Invite Safeguards

Keep:
- Small recent-contact memory to reduce spam.
- Bounded anti-repeat logic by age and count.
- Optional blocked-name list for known do-not-contact players.
- Clear manual override when the officer intentionally wants to retry.

Do not add:
- Permanent unbounded contact history.
- Verbose recruiter analytics.
- Heavy sync of all invite activity.

##### Mythic+ Party Invites

Keep:
- A lightweight guild-invite action in the Mythic+ party view for unguilded party members.
- An explicit user gesture so the default row click behavior still loads the planner.
- Guild-status checks based on the live party unit instead of cached assumptions.

Do not add:
- Automatic invites based on score or item level.
- Background invite attempts.
- Extra persistent storage just for party invite suggestions.

##### Invite Notes

Keep only if the APIs are safe and reliable:
- Optional welcome-note support for new guild members.
- Parsed join-date import from officer-note text when the note contains a recognizable join date.

Do not add:
- Note writes that require unsafe or combat-sensitive behavior.
- Complex note templating systems in the first pass.
- Persistent storage of raw officer-note text when only a join date is needed.

##### Join Date Handling

Join dates are structured member data, not note data.

Keep:
- `guildJoinDate` as the authoritative GH3 field for a toon's guild join date.
- Parsed join-date capture from officer-note text only as a source of structured data.
- Lightweight metadata describing how GH3 learned the date, for example source, captured time, and whether it has been applied.
- A user-safe path to apply detected join dates to owned toons in My Toons.

Preferred storage model:
- Do not store the officer note itself for this purpose.
- Parse the officer note and store only the resulting date and small source metadata.
- Treat the parsed date as a candidate if it was discovered indirectly.
- When accepted or trusted, write the value into the toon's `guildJoinDate` field so existing My Toons flows use the real field instead of a note mirror.

Recommended metadata fields:
- `guildJoinDate`
- `guildJoinDateSource`
- `guildJoinDateCapturedAt`
- `guildJoinDateCapturedBy`
- `guildJoinDatePending` when the date still needs user confirmation

Do not add:
- Officer-note mirrors in My Toons.
- Full note snapshots just to preserve join dates.
- Parallel note-based join-date storage once `guildJoinDate` exists.

#### Phase 2: Consider Later

Only after the officer-facing applicant flow is solid:

Possible additions:
- Prospect search using who-style lookups.
- Search filters for level, class, race, and zone.
- Invite queue with pause and resume.
- Lightweight whisper templates beyond the primary saved message.

Still avoid by default:
- Large scan engines with many moving parts.
- Deep automation that feels detached from manual officer review.
- Broad syncing of prospect search results.
- Dependency on third-party scoring systems.
- Minimap-first workflows.

## Storage and Size Management Goals

### What We Want

- Keep saved data intentionally small.
- Bound temporary invite state by retention windows.
- Keep user-authored data separate from disposable caches.
- Prune startup and shutdown-safe transient records.
- Use small summaries instead of detailed logs when possible.

### What We Do Not Want

- Unbounded invite logs.
- Long-term storage of transient applicant snapshots.
- Duplicate copies of the same operational data in multiple places.
- Persistent debug traces in normal user storage.
- Large rolling histories unless they are explicitly required.

### Data Rules

- Every cache must have either a max age or a max count.
- Every temporary list must be replaceable by a fresh scan or refresh.
- Every history-like table must justify why it is not pruned.
- Every new saved table needs a retention policy before implementation.

### Current Preferred Approach

Preferred:
- One addon database with better pruning and bounded tables.
- Compact state for invite workflows.
- Retention windows for recent-contact memory and invite safeguards.
- Structured join-date metadata instead of storing raw note text.
- Cleanup popup state that is transient and rebuilt from live roster data when possible.

Avoid unless proven necessary:
- Splitting functionality across multiple addon files purely to dodge data growth.
- Creating secondary saved-variable schemes before pruning is exhausted.
- Large archival subsystems.

## Safety and Blizzard Restrictions

### Lessons Learned

- No in-combat activities for officer tools that can trigger protected-action failures.
- Do not rely on UI behavior that is sensitive to combat lockdown.
- Avoid flows that create disable or ignore warnings from Blizzard.
- Avoid mass-action loops that try to automate repeated protected actions in one shot.
- Prefer explicit user clicks over hidden automation for invite or guild-management actions.
- Avoid default Blizzard dropdown patterns in active flows when safer addon-owned controls already exist.
- Keep chat and invite messaging conservative to reduce spam and blocked-action risk.
- If Blizzard limits repeated guild actions, use roster-adjacent launchers and macro-assisted handoff rather than trying to execute the entire batch directly.
- If a note contains structured data such as a join date, extract the structured value and store that value rather than treating the note as the long-term database.

### Hard Rules

- No invite automation that assumes combat-safe execution.
- No cleanup automation that runs while in combat.
- No design that depends on repeated protected calls firing automatically.
- No feature should require users to suppress Blizzard warnings just to use GH3.
- No officer-note dependency for long-term storage when GH3 already has a real field for the same information.

## Scope Exclusions

The following are intentionally out of scope for now:

- Large-scale recruiter analytics.
- Full prospect-search automation in the first invite release.
- Many saved message templates in v1.
- Minimap-driven recruiting workflows.
- External ranking or score integrations.
- Deep synchronization of invite activity across many users.
- Heavy audit logs for every invite attempt.
- Features that only work well by pushing combat or protected-action boundaries.

## Suggested Build Order

### Immediate

1. Keep Clean-up stable under the new tab layout.
2. Build Applicants.
3. Build Pending Invites.
4. Build Invite Message.
5. Build Invite Safeguards.

### After That

1. Add Invite Notes only if the implementation is safe.
2. Add bounded retention logic for invite-related saved data.
3. Review whether prospect search belongs in GH3 or should remain out of scope.

## Decision Filter For Future Requests

Before adding any new officer feature, verify all of the following:

- Does it fit under Clean-up or Invites without a new sidebar item?
- Can it be implemented without in-combat behavior?
- Can it be stored with bounded saved data?
- Does it reduce officer busywork without becoming a separate addon-sized system?
- Can it be explained in one paragraph to a guild officer without a training guide?

If the answer is no, it probably does not belong in GH3 right now.