Build Evaluation Developer Skill

Use this skill when modifying the weapon build evaluation logic in

internal/evaluator/

.

The evaluator is a high-performance DFS engine. Incorrect modifications can lead to exponential search times or suboptimal builds.

---

Scope & Intent

Use this skill when:

• Modifying the DFS algorithm in

  processSlots

• Adding new optimization metrics (e.g. Weight, Price)
• Adjusting pruning or bounding logic
• Debugging why a "best build" isn't actually optimal

---

Safety & Performance Invariants

1. Limited Run Scope:
   • Full Runs: Do NOT trigger a full evaluator run (

     task evaluator:start

     ) unless explicitly requested.
   • Test Mode: You MAY use

     task evaluator:start:test-mode

     for smoke tests. It uses a restricted subset of weapons and trader levels.
   • Focused Testing: Prefer unit tests, benchmarks, or integration tests targeting specific weapons.
2. Thread Safety:

   processSlots

   runs in parallel worker pools. NEVER use global variables or mutate shared structures (like the

   CandidateTree

   items) during the search.
3. Pre-Evaluation Setup: Before calling

   FindBestBuild

   , you MUST ensure the tree is initialized:

   weapon.UpdateAllowedItems()
   weapon.UpdateAllowedItemSlots()
   

4. Branch-Local Exclusions:

   excludedItems

   must be cloned (

   helpers.CloneMap

   ) when descending into a branch where a new conflict is introduced.

---

Algorithm Logic:

processSlots

Conflict Enforcement

Conflicts are enforced by the

excludedItems

map.

• Rule: If an item is in

  excludedItems

  , it cannot be chosen for the current slot.
• Rule: If an item is chosen, all its

  ConflictingItems

  must be added to the exclusion map for all subsequent descendants and siblings in that branch.

Tie-Breaking (

doesImproveStats

)

When comparing builds, we use primary and secondary stats:

• Recoil Focus: Primary is

  RecoilSum

  (lower is better). Tie-breaker is

  ErgonomicsSum

  (higher is better).
• Ergo Focus: Primary is

  ErgonomicsSum

  (higher is better). Tie-breaker is

  RecoilSum

  (lower is better).

---

Pruning & Bounding

Pruning skips branches that cannot mathematically beat the current

best

build.

Bounding Functions

• computeRecoilLowerBound

  : Sum of current recoil + minimum possible recoil from all remaining slots.

• computeErgoUpperBound

  : Sum of current ergonomics + maximum possible ergonomics from all remaining slots.

Pruning Locations

1. Item Selection: Before evaluating an item in a slot.
2. Empty Slot: Before evaluating the outcome of leaving a slot empty.

---

Caching Logic (

Cache

interface)

Caching uses memoization of "conflict-free" subtrees to avoid redundant DFS traversals.

The "Conflict-Free" Invariant

• An item is only cacheable if it has zero

  ConflictingItems

  .
• If an item has conflicts, its optimal subtree depends on which exclusions are active, making simple ID-based caching unsafe.

Clean Contribution

The cache stores the relative contribution of a subtree, not the absolute total. This allows the same cached result to be added to different parent builds.

---

How to Modify: Developer Checklist

When adding a new stat (e.g.,

Weight

):

1. Update Models: Add the stat to

   Build

   ,

   ItemEvaluation

   , and

   OptimalItem

   in

   evaluator.go

   .
2. Implement Bounding: Create

   compute[Stat]LowerBound

   or

   compute[Stat]UpperBound

   .
3. Update Comparison: Modify

   doesImproveStats

   to include the new stat in the priority chain.
4. Integrate Pruning: Call your new bounding function in

   processSlots

   .
5. Update Caching: Ensure the new stat is captured in

   CacheEntry

   and the

   Cache

   implementation.
6. Verify:
   • Run

     go test ./internal/evaluator/ -run TestCache

     to check cache correctness.
   • Run

     go test ./internal/evaluator/ -bench=. -benchmem

     to check for performance regressions.