Section 01: Promote /query-intel to an auto-triggerable Skill

Status: Complete Goal: /query-intel must be discoverable to the Claude Code harness as a Skill so its description can trigger auto-activation in relevant contexts (design discussions, debugging with unknown symbols, review prompts). The existing 14-line command file becomes a thin alias that forwards to the Skill, preserving explicit /query-intel <args> invocation.

Context: Today /query-intel exists only at .claude/commands/query-intel.md (14 lines). The Claude Code harness auto-triggers Skills (files matching .claude/skills/*/SKILL.md with a description frontmatter) based on context matching; it cannot auto-trigger commands. This is the single largest contributor to the underuse reported by the operator — even when Claude is about to grep for a symbol or read a reference-repo file, no ambient prompt surfaces the graph. Verified in the 2026-04-14 TPR: codex confirmed .claude/skills/query-intel/ does not exist (if [[ -d .claude/skills/query-intel ]]; then echo exists; else echo missing; fi → missing).

Reference implementations:

Ori .claude/skills/ori-syntax/SKILL.md: same paths-wildcard / info-forward SKILL shape we’re adopting — short description, reference-style body
Ori .claude/skills/improve-tooling/SKILL.md: richer auto-trigger description with numbered “TRIGGER when:” conditions — model for the intel Skill’s own trigger list

Depends on: Nothing. Runs in parallel with §02.

01.1 Create SKILL.md with auto-trigger frontmatter

File(s): .claude/skills/query-intel/SKILL.md (new)

The SKILL.md must have a description specific enough for the harness to auto-trigger. Vague descriptions don’t auto-trigger; the harness matches on concrete capabilities.

Create .claude/skills/query-intel/SKILL.md with frontmatter + body:

---
name: query-intel
description: >-
  Query the Neo4j-backed intelligence graph for symbol lookup, call graphs,
  cross-repo prior art, and issue/PR search. TRIGGER proactively when:
  (1) looking up who calls / is called by a function or type in Ori or a
  reference repo (rust, swift, go, koka, lean4, gleam, elm, roc, zig, ts);
  (2) finding the Rust/Swift/Koka equivalent of an Ori function before manual
  browsing; (3) inventorying symbols in a module before editing; (4) checking
  prior art on a compiler design question (exhaustiveness, inference, ARC,
  RC elision, etc.); (5) assessing blast radius before a refactor. The graph
  houses 191K symbols, 505K CALLS edges, and 298K issues across 11 repos,
  synced on every commit — ~100x faster than grep. Uses scripts/intel-query.sh
  which degrades gracefully when the graph is unavailable.
paths:
  - "**"
---

# /query-intel

Canonical surface for the intelligence graph. See `.claude/rules/intelligence.md`
for the full workflow inventory (when to query, how to interpret results,
subsystem presets).

## Invocation

scripts/intel-query.sh [args…]


Always use the wrapper — never open-code Neo4j access.

## Subcommand reference

### Code symbol queries (Ori + reference repos)
- `symbols <name> [--repo R] [--kind K]` — find symbols by name
- `callers <name> --repo ori` — who calls this function?
- `callees <name> --repo ori` — what does it call?
- `file-symbols <path-fragment> --repo ori` — all symbols in matching files
- `similar <name> [--repo rust,swift,go,koka]` — semantic equivalents

### Issue/PR search (external repos)
- `search <terms>` — full-text search
- `compare <terms>` — cross-repo convergence (same issue in 2+ languages)
- `fixed <terms> [--repo ...]` — closed-as-fixed issues
- `hot [--repo R]` — highly-reacted issues
- `ori-arc` / `ori-inference` / `ori-codegen` / `ori-patterns` / `ori-diagnostics` — subsystem presets
- `sentiment pain|controversy|excitement [--repo R]` — ranked by emotional weight
- `landscape [--repo R]` / `ori-sentiment` — aggregated sentiment maps

### Administrative
- `status` — graph health + node/edge counts
- `cypher "<query>"` — raw Cypher escape hatch

## Output mode
- Default: JSON (for agent pipelines). (§08 changes this to tty-aware.)
- `--human`: human-readable text.

## Related canonical docs
- `.claude/rules/intelligence.md` — workflow inventory, subsystem mapping
- `.claude/skills/dual-tpr/compose-intel-summary.md` — SSOT summary template (§03)

Verify harness discovery: after the write, the next system reminder’s “available skills” block MUST list query-intel with its description. Confirmed: post-write system reminder listed query-intel with its full description (block-scalar description rendered correctly, description includes all 5 trigger conditions).
Subsection close-out (01.1) — MANDATORY before starting 01.2:
- Tasks above are [x] and the SKILL.md is valid (harness discovered it)
- Update 01.1 status to complete in section frontmatter
- Run /improve-tooling retrospectively on 01.1 — No tooling gaps require implementation. The SKILL.md creation relied on the Write tool + a 30-second python3 YAML parse check + passive harness system-reminder confirmation — all sufficient. Observed friction points: (a) ~5 min researching whether paths: is a recognized SKILL.md field (resolved: .claude/rules/*.md files use it, no existing SKILL.md does; the Claude Code harness’s actual field list is not documented in this repo) and (b) manual python3 YAML parse validation instead of a dedicated tool. Neither candidate (a doc note on platform-level frontmatter schema, or a new scripts/lint-skill.sh) meets the recurrence+payoff bar for this subsection — candidate (a) documents platform behavior that could drift from the actual harness; candidate (b) saves ~30 seconds per Skill creation and the repo creates Skills infrequently. If §01.2 or §05 hits identical friction, revisit then.
- Run /sync-claude on 01.1 — Claude artifact sync 01.1: SKILL added, no CLAUDE.md / rules changes needed. Verified via grep: only 1 reference to /query-intel in CLAUDE.md (line 38) and zero in .claude/rules/*.md — all agnostic to Skill-vs-command backing. .claude/rules/intelligence.md structure (Availability / When to Query / How to Query / Symbol-First Workflow / Subsystem Mapping / How to Use Results) unchanged by the new Skill — no new preset, no new query type, no new subsystem row. The Skill provides an auto-trigger pathway over the existing command without changing any documented claim.
- Repo hygiene check — diagnostics/repo-hygiene.sh --check → clean, no scratch files from SKILL.md iteration.

01.2 Reduce command file to alias + verify harness discovery

File(s): .claude/commands/query-intel.md (modify)

The command file today is the sole surface for the tool. After §01.1 it’s redundant with the Skill. Reduce it to an alias that forwards arguments, preserving /query-intel <args> for explicit invocations while the Skill is the default for auto-trigger cases.

Replace the body of .claude/commands/query-intel.md with a thin alias:

---
name: query-intel
description: "Query the intelligence graph. See .claude/skills/query-intel/SKILL.md for the full capability surface."
allowed-tools: Bash, Read, Grep, Glob
argument-hint: "[subcommand] [args...] — see .claude/skills/query-intel/SKILL.md for the full list"
---

# /query-intel

This command is a thin alias. The canonical capability surface lives in
`.claude/skills/query-intel/SKILL.md` — read that for the subcommand reference,
output formats, and workflow guidance.

Run: `scripts/intel-query.sh $ARGUMENTS`

If `$ARGUMENTS` is empty, run: `scripts/intel-query.sh status`

Smoke test: explicit invocation still works — /query-intel status must produce status output, /query-intel symbols IteratorValue --repo ori must produce symbol rows. Verified via the underlying wrapper scripts/intel-query.sh (slash commands are user-invoked only, but the command file’s single action is scripts/intel-query.sh $ARGUMENTS, so the wrapper IS the target). Results: status returned full graph health JSON (Neo4j 5.26.24 ok, 11 repos, 191K symbols, 298K issues, 505K CALLS edges); --human symbols IteratorValue --repo ori returned [sum_type] IteratorValue — compiler/ori_patterns/src/value/iterator/mod.rs:53.
Verify SKILL.md is the harness default for ambient references (no regression where the harness loses discovery after the command body shrinks). Post-§01.2 system reminder shows two query-intel entries coexisting: (1) Skill entry with the full description from §01.1 (unchanged, still auto-trigger-worthy), (2) Command entry with its reduced description “Query the intelligence graph. See .claude/skills/query-intel/SKILL.md for the full capability surface.” The command now defers to the Skill for canonical guidance while remaining available for explicit /query-intel <args> invocation. No Skill discovery regression.
Subsection close-out (01.2) — MANDATORY before section close:
- Tasks above are [x] and both explicit + Skill-triggered paths exercise cleanly
- Update 01.2 status to complete
- Run /improve-tooling retrospectively on 01.2 — No tooling gaps requiring implementation. §01.2 was the simplest kind of edit: one Read + one Write to replace a 27-line file with a 16-line thin alias. Smoke tests were two chained scripts/intel-query.sh invocations that returned expected output first try. Harness discovery was passively verified via the post-write system reminder (same mechanism as §01.1). No workflow friction, no missing-flag frustrations, no confusing output. The candidates considered in §01.1 (lint-skill.sh, doc note on SKILL.md frontmatter schema) remain below the recurrence+payoff bar — if §05’s 4-skill authoring session compounds the same friction, revisit then.
- Run /sync-claude on 01.2 — Claude artifact sync 01.2: CLAUDE.md line 38 reference (/query-intel similar, /query-intel callers/callees) is agnostic to Skill vs. command backing; no edit needed. .claude/rules/intelligence.md unchanged. The command file’s description text did change (now points to SKILL.md as canonical surface), but that’s a user-facing UI string in the harness’s available-skills listing, not a documented-API claim in any rules file. No drift.
- Repo hygiene check — diagnostics/repo-hygiene.sh --check → clean.

01.R Third Party Review Findings

None.

01.N Completion Checklist

Exit Criteria: .claude/skills/query-intel/SKILL.md exists, appears in the harness skill listing, and both explicit (/query-intel ...) and Skill-auto-triggered invocations route to scripts/intel-query.sh. The command file is reduced to a ≤20-line alias. No regression in ./test-all.sh or plan_corpus validation.