dota-item-recommender
Governs item recommendation logic in Dota AI Coach — the candidate-generation/scoring/ranking/explanation pipeline, required context inputs (hero, role, facet, patch, bracket, minute, level, gold, inv
SKILL.md.claude/skills/dota-item-recommender/SKILL.md
GitHubDota Item Recommendation
Core rule
NextItem ≠ ItemWithHighestWinRate
An item's aggregate win rate collapses everyone who ever bought it —
every hero, every role, every patch, every game minute, every matchup —
into one number. The item that's statistically associated with winning
the most, on average, across all of that, is very often not the right
item for this specific hero, at this specific minute, against this
specific enemy lineup. Treating win rate as the recommendation is the
single most tempting shortcut in this domain, because it's cheap to
compute and looks like it's grounded in data — resist it. This is the
same principle dota-domain states generally ("never recommend an item
solely from item win rate"); this skill is where it becomes an actual
system design.
Required context
A recommendation is only as good as the context it's conditioned on. The
full list, with reasoning for why each matters, is in
references/context-inputs.md — summary:
- hero and role — what the hero's kit needs, and what job they're doing (farm priority, initiation, utility) shape what's valuable at all.
- facet — a facet can shift a hero's kit enough to change item
priorities (per
dota-domain). - patch — item costs, mechanics, and hero balance all shift by patch; a correct answer on one patch can be wrong two patches later.
- bracket — what's correct/achievable differs by skill level.
- minute and level — timing determines what's actually reachable and what the current power-spike window calls for.
- gold (current and near-future income) — a theoretically ideal item the player can't afford yet isn't a next-item recommendation.
- current inventory — recommending an item already owned, or one redundant with what's owned, is a correctness bug.
- purchase sequence — the order items were bought signals what problem the player has already tried to solve, and what's likely still needed.
- allied heroes — synergy and coverage: don't recommend redundant utility the team already has covered elsewhere.
- enemy heroes and visible enemy items — counters and threats are
matchup-specific and time-varying; see
dota-fairplay'sVISIBLE_SCREENclassification for what "visible enemy items" may legitimately include. - damage composition and disable composition — of both teams; itemization should respond to what's actually threatening the player, not a generic profile.
- power spikes — whose window is active/imminent should inform
urgency and choice (per
dota-domain's game-flow concepts). - player comfort — a player's familiarity with an item build affects whether it's actually the right real-world recommendation, not just the theoretically optimal one.
Treat missing context as a real constraint on recommendation quality, not
something to silently paper over with a default — see
references/context-inputs.md for how to handle it.
Pipeline: candidate generation → scoring → ranking → explanation
These four stages are kept structurally separate — not just
conceptually, but as distinct components with distinct responsibilities,
testable independently. Full detail in references/pipeline.md; summary:
- Candidate generation — produces the set of items worth considering at all, given hero/role/inventory/gold-trajectory constraints. This stage's job is recall (don't miss a genuinely relevant item), not precision — over-inclusion here is cheap; a missed candidate can never be recommended no matter how good scoring is.
- Scoring — assigns each candidate a score given the full context.
This is where the actual "is this good, right now, for this
situation" judgment happens, combining
dota-domainstrategic reasoning with any model-based scoring perdota-ml. - Ranking — orders scored candidates and selects what to surface (top item, ranked alternatives). Ranking can apply constraints scoring doesn't (e.g. diversity across alternatives, deduplication of near-equivalent items) without needing to re-touch scoring logic.
- Explanation — produces human-readable reasoning for the top recommendation(s). See "LLM boundary" below — this stage may use an LLM; the prior three must not depend on one.
Keeping these separate means a scoring bug can be fixed without touching
ranking, and an explanation-quality issue never requires touching the
actual decision logic — see references/pipeline.md for why collapsing
these stages is a recurring temptation worth resisting.
LLM boundary
LLMs may explain recommendations but may not be the primary item
decision engine. This is dota-ml's "ML decides, LLM explains"
principle applied specifically here:
- Candidate generation, scoring, and ranking must be deterministic/
model-based logic (rules,
dota-ml-governed models) that can be tested, evaluated, and reasoned about independently of any LLM call. - The explanation stage may use an LLM to turn the structured output (below) into natural-language reasoning for the player, but the LLM must not be asked to decide the item, re-rank candidates, or override the score/ranking it's explaining — its job is narration of an already-made decision, not the decision itself.
- If an LLM's explanation seems to justify a different item than what was actually recommended, that's a bug in the explanation stage, not a sign the LLM found a better answer — investigate why the structured reasoning (reasonCodes) didn't actually support the recommendation scoring produced.
Required structured output
Every recommendation must be emitted in this shape — not just for the top pick, but for the alternatives considered:
itemId: the recommended item's identifier
score: the scoring stage's output for this item (see pipeline.md
for what this represents and how it's produced)
confidence: how much the system trusts this score, given available
context — see confidence-and-bias.md; not the same thing
as the score itself
reasonCodes: structured, enumerable reasons this item scored as it did
(e.g. COUNTERS_ENEMY_BURST, FILLS_DISABLE_GAP,
MATCHES_POWER_SPIKE_WINDOW, AFFORDABLE_NOW) — this is what
the explanation stage consumes and what makes the
recommendation auditable
alternatives: other candidates considered, each with their own score/
reasonCodes, so the player (and any reviewer) can see what
else was weighed and why it ranked lower
See references/output-schema.md for the full schema, reasonCode
taxonomy, and worked examples. Prefer this structured shape over free
text everywhere in the pipeline — per dota-domain's general preference
for structured concepts over free-text assumptions, this is what makes
recommendations testable and what the explanation stage narrates rather
than invents.
Avoiding survivorship and selection bias
Historical item data is skewed by who chose to buy what — see
references/confidence-and-bias.md for the concrete mechanisms (e.g.
players who bought an item disproportionately already had a favorable
game state, so raw purchase-outcome correlation overstates the item's
actual causal value) and how candidate generation/scoring should account
for this rather than naively fitting to observed purchase-outcome
correlations. This connects directly to dota-ml's baseline-first and
leakage-testing discipline — a scoring model here is subject to the same
rules as any other model in this project.
Relationship to other skills
dota-domain— the strategic vocabulary (roles, damage types, power spikes, counters) this skill's context inputs and scoring logic are built on.dota-ml— governs how any model-based scoring is built, validated, and shipped (baseline-first, leakage tests, calibration); this skill governs what that model is for and how its output fits the recommendation pipeline.dota-fairplay— governs what "visible enemy items" and other live inputs may legitimately include; this skill's context inputs must respect that classification.dota-architecture— this skill's pipeline maps onto the Recommendation Engines / Recommendation Orchestrator layers; the four-stage separation here is a specific instance of "recommendation engines consume normalized features," not a competing structure.