update skills/ for six-tool trace surface

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: HumanBean17

skills/README.md

@@ -1,6 +1,6 @@
 # skills/ — RAG navigation skills for the java-codebase-rag MCP
 
-Two self-contained skills for navigating indexed Java codebases via the 5-tool MCP (`search` / `find` / `describe` / `neighbors` / `resolve`). Skills are agent-side prompt scaffolding — they are **not** a second MCP API and **not** CLI subcommands.
+Two self-contained skills for navigating indexed Java codebases via the 6-tool MCP (`search` / `find` / `describe` / `neighbors` / `resolve` / `trace`). Skills are agent-side prompt scaffolding — they are **not** a second MCP API and **not** CLI subcommands.
 
 ## Which skill to use
 
@@ -26,7 +26,7 @@ skills/
 
 The comprehensive operating manual. Includes:
 
-- **Five-tool reference** — `search`, `find`, `describe`, `neighbors`, `resolve` with full argument shapes
+- **Six-tool reference** — `search`, `find`, `describe`, `neighbors`, `resolve`, `trace` with full argument shapes
 - **Node kinds** — Symbol, Route, Client, Producer
 - **Edge taxonomy** — stored edges, composed dot-keys, direction semantics
 - **NodeFilter reference** — all filter keys by node kind, strict frame rules
@@ -56,7 +56,7 @@ The tactical tracing skill. Includes:
 │   Implementation: explore-codebase / navigate-codebase       │
 ├──────────────────────────────────────────────────────────────┤
 │ Layer 2 — Composable primitives (the MCP API)                │
-│   search, find, describe, neighbors, resolve                 │
+│   search, find, describe, neighbors, resolve, trace          │
 ├──────────────────────────────────────────────────────────────┤
 │ Layer 1 — Storage primitives                                 │
 │   Kuzu Cypher + LanceDB tables                               │

skills/navigate-codebase/SKILL.md

@@ -19,13 +19,14 @@ The graph exists to confirm structure you already have a hypothesis about — no
 
 ## Tools
 
-`search`, `find`, `describe`, `neighbors`, `resolve`.
+`search`, `find`, `describe`, `neighbors`, `resolve`, `trace`.
 
 - **`search(query, table?, hybrid?, limit?, filter?)`** — ranked chunk retrieval. `table`: `java`|`sql`|`yaml`|`all` (default `java`). `limit` default 5.
 - **`find(kind, filter, limit?)`** — structured listing. `kind`: `symbol`|`route`|`client`|`producer`. `filter` is required.
 - **`describe(id)`** — full node record + `edge_summary` (per-label in/out counts). 1 arg.
 - **`neighbors(ids, direction, edge_types, filter?, edge_filter?, limit?)`** — one hop. `direction` and `edge_types` required. `filter` applies to the other node. `edge_filter` (CALLS only) applies to edges before pagination.
 - **`resolve(identifier, hint_kind?)`** — identifier lookup. Returns `one`, `many`, or `none`.
+- **`trace(ids, direction, edge_types, max_depth?, max_paths?, prune_roles?, fan_out_cap?, collapse_trivial?)`** — multi-hop BFS with server-side pruning. Use for 3+ hop path questions or when `neighbors` returns high fan-out (>8 CALLS edges). `direction` and `edge_types` required. `max_depth` 1–5 (default 3). `prune_roles` soft gate (edges recorded, frontier stops). `fan_out_cap` per-node limit (default 5). Cross-service edges are boundary signals — BFS stops at the service boundary.
 
 ### NodeFilter keys (for `find`, `search.filter`, `neighbors.filter`)
 
@@ -48,8 +49,8 @@ The graph exists to confirm structure you already have a hypothesis about — no
 Before each MCP call, output one short line:
 
 ```
-Q-class: <semantic | structured | inspect | walk>
-Pick: <search|find|describe|neighbors|resolve>  Why: <≤8 words>
+Q-class: <semantic | structured | inspect | walk | trace>
+Pick: <search|find|describe|neighbors|trace|resolve>  Why: <≤8 words>
 ```
 
 Then use real JSON shapes.
@@ -119,7 +120,7 @@ Hypothesis: "assign() persists via a repository"
 
 ### Open-ended neighbors loops
 
-Never chain `neighbors(out, CALLS)` calls without a stopping condition. Each hop multiplies the surface area. After 2 hops, stop and reassess.
+Never chain `neighbors(out, CALLS)` calls without a stopping condition. Each hop multiplies the surface area. After 2 hops, stop and reassess — or escalate to `trace` to batch the remaining traversal with server-side pruning.
 
 ### Walking all edge types at once