Add in-repo hypaware-query skill with graph-vs-raw query routing guidance

[philcunliffe]

What

Brings the hypaware-query agent skill into the repo under .claude/skills/ (the tooling-lives-in-repo convention, so every clone has it) and extends it with guidance on when agents should route a question through the context graph (node/edge datasets, hyp graph neighbors) versus raw ai_gateway_messages SQL.

Why

Agents querying HypAware data underuse the graph, falling back to slow and fragile scans over the messages table. The new guidance was distilled from an empirical comparison of 15 query types run both ways against a live install (143k-row messages table, 5.4k-node graph). Headline findings baked into the skill:

• Derived predicates are the strongest reason to use the graph. Concepts computed at projection time (skill activation per LLP 0073/0074, program extraction per LLP 0077) cannot be reliably reconstructed ad hoc: a 3-surface LIKE approximation returned 52 sessions where the canonical rules give 44, and a first-token "program" approximation returned 470 garbage tokens against the graph's 86.
• Multi-hop questions are graph-only in practice. A co-occurrence query answered by graph neighbors --depth 2 in 0.17s either threw (malformed tool_args row) or ran past a 2-minute timeout as a correlated raw subquery.
• The raw route has silent footguns, now documented: LIKE on the JSON-typed tool_args/attributes columns matches zero rows without erroring; json_extract throws on a malformed row unless pre-filtered by tool_name; session identity is session_id (the conversation_id column is mostly null).
• The graph has its own pitfalls, also documented: File-node identity splits between repo-scoped (owner/repo:path) and absolute-path keys; neighbors prints display-truncated node ids and ignores --format json; SQL over edge needs literal node_id anchors (scalar-subquery anchors take ~33s vs ~3s literal vs ~0.2s neighbors).

The skill leads with a generic routing rule (identifiers/derived/multi-hop/inventory/normalization -> graph; counts/content/ordering/attributes -> raw; graph picks the scope, raw reads inside it) and includes the full graph-to-content drill-down recipe (Session natural_key = session_id, tool_result_for pairs results to calls, message_index windows for surrounding context).

Notes

• Docs-only: one new file, no code or test changes.
• Em dashes stripped per the repo style rule.

🤖 Generated with Claude Code