poe_mcp_suite: Instructions file for Claude Code

poe_mcp_suite — Notes for Claude

Setup / post-pull: If this is a fresh clone or you just ran git pull, read INSTALL.md to check for new installation steps or tools that need running.

Session-start update check (automated via hook): A SessionStart hook (.claude/settings.json → scripts/session-start-check.sh) runs the session-boundary checks — suite upstream, PoB version, game-patch signal, league-end proximity, and playbook hygiene (uncommitted drafts, unshared-vs-upstream changes, missing wrapper skills; each announced once) — and injects a [Session-start update check] message into context only when action is needed. If that message is present, relay it to the user early in your first response. If it's absent, everything is current — do not re-run the check manually. (Manual fallback if hooks are disabled: git fetch origin --quiet + git log HEAD..origin/main --oneline; compare the first line of %APPDATA%\Path of Building Community\changelog.txt against the latest tag at https://api.github.com/repos/PathOfBuildingCommunity/PathOfBuilding/releases/latest.)

Cursory-vs-detailed gate (cross-cutting — applies to EVERY task): Before doing anything, decide whether the request is cursory (a quick lookup/answer — proceed directly, no playbook) or detailed (multi-source, multi-stage, or >10K expected tokens — engage the matching playbook and pause for approval before pulling data). This triage is domain-independent and lives here on purpose; the per-domain skills assume it has already happened. Full criteria in playbooks/README.md section 1.

Freshness check (a SEPARATE axis from cursory/detailed): The cursory gate measures effort; freshness measures whether the answer depends on patch-specific game data. They're independent — a question can be cheap (one lookup) yet still be exactly what stale knowledge gets wrong. Classify the content:

• Timeless / conceptual — how a mechanic works, general tactics, the math — safe to answer from your own knowledge.
• Patch-specific factual lookup — what mods can roll on an item, what a passive node grants, a unique's current stats, prices, league specifics — your built-in PoE knowledge (~mid-2024) is unreliable and the game changes constantly. Err on the side of freshness: fetch authoritative data by default. On factual data you can never go wrong by being current; the only cost is time, context, and a few API calls. Almost every such lookup has a cheap authoritative path — get_tree_node, search_crafting_mods / list_craftable_mods_for_base, get_essence_detail, calculate_mod_odds, fetch_wiki_page, or live PoB. Prefer fetching over answering from memory; only ask "quick take from memory, or pull current data?" when the fetch would be genuinely expensive or multi-step. This is a problem for everyone — PoE has too much data, changing too often, to keep current from memory; the tools exist precisely so you don't have to.

Model-aware freshness index: before asserting how any patch-specific mechanic/item/system works — or at the stage of a detailed analysis where one is load-bearing — consult reference_data/freshness_index.md. It lists post-training mechanics keyed by patch, alongside each model's training cutoff, so you know what the model you're currently running as cannot be trusted on (the generic "~mid-2024" above is replaced by your model's real cutoff from the index's cutoff table). Anything in the index newer than the running model's cutoff = verify before asserting. The freshness-check skill auto-surfaces this; detailed-analysis playbooks consult it at pre-flight (playbooks/README.md §2e).

Playbooks & skills: Detailed analysis procedures live in playbooks/ (the single source of truth). Thin wrapper skills in .claude/skills/ auto-trigger on matching detailed-scope requests and tell you to read playbooks/README.md (shared meta-framework: context management, league pre-flight, narration norms, trust hierarchy) plus the relevant specific playbook. If a skill fires for what is actually a cursory task, honor the gate above and answer directly instead. If no playbook exists for a recurring detailed task shape, note that and write one (then add a wrapper skill).