feat(skills): add /navigate-codebase skill

[HumanBean17]

Summary

• Adds /navigate-codebase skill — a lighter alternative to /explore-codebase for targeted tracing questions
• Encodes RAG-first, graph-for-precision strategy to prevent agents from drowning during multi-hop graph traversal
• 195 lines (vs /explore-codebase's 322) — deliberately focused, no duplication of full tool reference

Key content

• 4 navigation rules: search before you walk, always filter, depth discipline (2-3 hops), hypothesis-driven hops
• Anti-patterns section: open-ended neighbors loops, walking all edge types, following into infrastructure
• Side-by-side worked example: correct RAG-first approach vs drowning approach

Test plan

• Verify skill loads correctly in an MCP client
• Confirm /explore-codebase is not affected (separate file, no shared state)
• Check that all exclude_roles usage is inside filter={} (fixed during review)

🤖 Generated with Claude Code

Refs #232

[HumanBean17]

Review: /navigate-codebase skill

Verdict: Good direction, needs a few fixes before merge

The skill is well-structured, addresses a real problem (#232 Track 1), and the 4 navigation rules + anti-patterns section are the right abstractions. The worked example is effective. A few things to address:

---

1. Self-containment gap — dead cross-references (blocking)

The skill references /explore-codebase three times:

• "See /explore-codebase for full tool reference, argument shapes, and edge taxonomy."
• "If the call fails or returns nothing useful, use the recovery playbook in /explore-codebase."
• "Use /explore-codebase when you need the full operating manual..."

If an agent loads only /navigate-codebase (the typical skill-loading model — one skill at a time), these references are dead. The agent can't invoke another skill mid-conversation to fill the gap. Two options:

• (A) Make it self-contained for the navigation use case: inline the essential tool args, the key NodeFilter fields, and a compact recovery table. You already have 195 lines — adding ~30 for the critical reference material keeps it well under explore-codebase's 322.
• (B) Document that both skills should be loaded together (in the description field and in skills/README.md), and accept that agents using only navigate-codebase get a degraded experience.

I'd recommend (A) — the whole point of this skill is being a lighter, standalone alternative.

2. skills/README.md is stale (blocking)

The README currently says "A single self-contained skill" and only lists explore-codebase. The layout section, the three-layer diagram, and the relationship docs don't mention the new skill. This needs to be updated to describe both skills and when to use each.

3. Missing edge_filter context (non-blocking)

Rule 2 mentions exclude_callee_declaring_roles=["OTHER"] but doesn't explain that this goes in the edge_filter parameter (not filter). An agent following this skill wouldn't know where to put it. One sentence would fix this:

On CALLS out edges, pass edge_filter={"exclude_callee_declaring_roles": ["OTHER"]} to drop JDK/Spring calls.

4. Composed edges are invisible (non-blocking)

The quick-reference edge table only covers stored edges. For tracing, OVERRIDDEN_BY (and its dot-keys like OVERRIDDEN_BY.EXPOSES) are critical when you land on an interface method and need to trace what concrete implementations call. Consider adding one row:

| OVERRIDDEN_BY | Finding concrete method implementations | out on non-static method → overriders |

5. Minor: branch prefix

AGENTS.md says chore/<topic> is for "repo hygiene (docs, tooling, deps)" while feat/<topic> is for "landed-feature work". A new user-facing skill is arguably a feature. Not a blocker, just a consistency note.

---

What's good

• The 4 navigation rules are clear and actionable — especially Rule 3 (depth discipline) and Rule 4 (hypothesis-driven hops).
• Anti-patterns section is excellent — each one explains why it's bad, not just what to avoid.
• The side-by-side worked example (correct vs drowning) is the strongest teaching device in the skill.
• exclude_roles is consistently shown inside filter={} throughout.
• No code changes, zero risk — exactly what Agents drown during multi-hop graph tracing — RAG + search outperforms neighbors loops #232 Track 1 promised.

---

Fix items 1 and 2, optionally 3 and 4, and this is ready to merge.