cortex-audit

name	cortex-audit
description	Fetch the audit envelope for a past Cortex turn or query. Returns caller, intent, scope, per-field counts, latency, cache hit/miss, and a structured trace of what each retrieval lane returned. Use this when the user asks "what did Cortex do?", "why did the model see X?", or wants to debug retrieval quality on a specific turn.

cortex-audit

Use this skill to debug retrieval — what Cortex did on a past turn, not what the model did with it.

When to use

• The user asks "why did Cortex return X?" / "what context did the model see?" / "audit turn <id>".
• The model just produced a result that looks wrong, and the user wants to check whether the bad output came from Cortex retrieval or the model itself.
• A law violation surfaced; the user wants to confirm the audit envelope captured it.

Do NOT use this skill to:

• Pull fresh context for the current task — use cortex-context.
• Search for events — use cortex_query with intent=free_search.

How to invoke

Call cortex_query with the audit intent's substitute (free search against the audit stream):

{
  "intent": "free_search",
  "query": "query_id:<turn_id>",
  "include": ["snippets"],
  "scope": { "topics": ["audit"] },
  "budget_ms": 200
}

The audit stream (cortex.events.query_audit) carries one envelope per query. The query_id is what the spec-12 bundle's leading comment surfaced — copy it from there.

How to use the response

The audit envelope carries:

• caller — claude-code / dashboard / analysis.
• intent — pre_change_context / decision_lookup / similar_problems / law_check / free_search.
• scope — repo, files, topics, since.
• counts — per-field result counts (snippets, decisions, violations, graph_neighbors, similar_turns, laws_active).
• latency_ms — total wall-clock.
• cache — hit / miss.

Summarise: "Cortex ran a <intent> against scope <scope> and returned <count> results in <latency> ms (cache: <state>). The retrieval lanes that fired were: <lanes>."

If the audit shows reason: scope_forbidden or rate_limited, flag it explicitly — the model didn't see the bundle the user might have expected.

Empty result

If no audit envelope matches the query_id, either the turn didn't issue a Cortex query (pre-thinking was disabled or the adapter wasn't running) or the audit stream rotated past it. Note both possibilities to the user.