# Repository Guidelines

## Project Structure & Module Organization
`DiamondThreatMeter` is a World of Warcraft addon for 2.4.3. Core entry points are `DiamondThreatMeter.toc`, `DiamondThreatMeter.lua`, and `DiamondThreatMeter.xml`.
- `common/`: shared data tables and utility modules (abilities, items, localisation, combat parsing).
- `engine/`: threat computation, combat event handling, party/network sync, API adapters.
- `gui/`: XML/Lua UI widgets, lists, warnings, and options panels (`gui/options/`).
- `Libs/`: bundled third-party Lua libs (`LibStub`, `StormforgeThreatLib`).
- `gfx/`, `snd/`: static textures/fonts and sound assets.
- `docs/`: legacy behavior notes and reference documentation.

## Build, Test, and Development Commands
This repo has no standalone build step; development is validated in-game.
- `Compress-Archive -Path * -DestinationPath ..\DiamondThreatMeter.zip -Force`: package addon for distribution.
- `Copy-Item -Recurse -Force . "<WoW>/Interface/AddOns/DiamondThreatMeter"`: install/update local test copy.
- In-game reload after edits: `/reload`.
- Use existing engine test helpers in `engine/test.lua` via addon slash/test hooks when validating talent/gear/version flows.

## Coding Style & Naming Conventions
- Use tabs for indentation to match existing Lua/XML files.
- Keep global API surface prefixed with `DTM_` (for example, `DTM_Engine_*`, `DTM_GUI_*`).
- Prefer lowercase file names in existing module style (`threatList.lua`, `combatEvents.lua`) and keep XML/Lua pairs aligned.
- Preserve `.toc` load order comments and constraints; order is behavior-critical for `engine\engine.xml` and `gui\GUI.xml`.

## Testing Guidelines
- Primary testing is manual in a 2.4.3-compatible client.
- Smoke test each change in party/raid combat: threat updates, aggro warnings, and options panel rendering.
- When touching parsing or modifiers, exercise at least one tank class and one DPS class scenario.
- If adding diagnostics, keep them behind existing debug/test entry points instead of always-on chat output.

## Commit & Pull Request Guidelines
- Commit messages in this repo are short, imperative, and scope-focused (for example: `Optimize threat list aggro handling`, `Add combat log parsing toggle (#4)`).
- Keep commits single-purpose and mention issue IDs when relevant.
- PRs should include: gameplay impact summary, touched modules (for example `engine/threatList.lua`, `gui/options/*`), manual test steps, and screenshots only for UI-visible changes.
