Kartik-Doye/Ravengard-AI-Recruiter / .agents/skills/spelunk
spelunk
VerifiedMaps an unfamiliar repository from a concrete question by finding manifests, entry points, execution paths, dependencies, churn, ownership, and risk. Use for codebase onboarding, impact analysis, or locating where behavior lives before planning or debugging.
spelunk: understand before touching
Your output is context other skills consume. The map must be compact enough to inject later without tax, and every claim in it must be tied to a real file path you actually saw.
When NOT to use
PROJECT_CONTEXT.mdat the root already covers the need and is fresh, read that instead.- The question is answerable by reading one obvious file. Just read it.
- Empty or greenfield repository: say that and stop.
Prerequisites
Filesystem + search only. Git enriches (churn, history) but is optional. No network required or used.
Authority and evidence boundary
Spelunk is read-only discovery by default. It maps observed repository state; it does not authorize edits, run state-changing scripts, infer secrets, or promote a hypothesis into architecture. If a requested answer needs a runtime, production, private service, or external source, state the boundary and route to the appropriate investigation rather than simulating certainty.
For deep, risk-map, monorepo, or stale-map work, keep an evidence record using references/evidence-protocol.md: question, scope, paths read, path traced, observed facts, inferences, unknowns, and recheck trigger.
Modes
| Mode | When | Stop rule |
|---|---|---|
quick | Task-specific question ("where is auth?") before acting | answer is supported |
deep | Whole-project understanding; may produce docs/repo-map.md | major boundaries and unknowns are mapped |
teach | User is new to the project and wants to learn it | one representative path is explainable |
risk-map | Before refactors or handoffs | evidence-backed hotspots are identified |
Pick the mode from the request; when unsure, default to quick and offer
deep once. In deep and risk-map modes, start with the bundled
scanner, scripts/inventory, to collect file distribution, largest files,
TODO/FIXME debt, test/source
ratio, git churn hotspots). Read its output selectively; it informs the
map, it is not the map.
In a monorepo, identify repository root, package boundaries, workspace tooling, and the app that owns the question before reading shared utilities. Do not mistake a root manifest for the target application's runtime.
Discovery order (all modes)
- Manifests before code. Identify ecosystems from
package.json/pyproject.toml/go.mod/Cargo.toml/pom.xml/build.gradle*/Gemfile/composer.json/pubspec.yaml/ etc. Scripts, dependencies and tooling follow from these: don't guess them. - Entry points.
main/indexfiles, server bootstrap, app router directories,Dockerfile/ProcfileCMD. Where execution starts tells you how everything else hangs together. - Trace one execution path early. Before broadening, follow a single representative request end-to-end (route → middleware → handler → service/model → response) with real symbols. This grounds every later claim; a map built without one traced path drifts into abstraction.
- Routing and config. Route definitions and config files reveal the feature surface without reading implementations.
- Precise symbols before text search. If an index exists (LSP, ctags, IDE symbols), resolve the symbol there first; fall back to grep, then read only the hits, in ranges, not whole files.
- Targeted reads. Read what the task actually touches. Use ranged reads when a whole file would add substantial irrelevant context.
Never: recursive full-directory reads, whole-file dumps of large files, or "read everything to be safe." Budget overflow → deliver the partial map with an explicit "not covered" list.
If a search result is ambiguous, trace a real import, registration, route, or test reference before assigning ownership. Names and directory placement are leads, not proof of execution path.
What to record
Full checklist with per-ecosystem detection hints lives in
references/discovery-map.md: read it in deep mode, or when the
checklist item isn't obvious. Core set:
- languages, frameworks, package manager, key dependencies;
- commands: dev / test / lint / typecheck / build (as actually defined in manifests and CI, not guessed);
- entry points and request lifecycle in one sentence;
- modules and their boundaries; data models and where migrations live;
- external services and env vars (names only: never values);
- auth mechanism; state management approach;
- CI/CD; conventions worth respecting; hotspots (large or high-churn
files, via
git logwhen available).
Mode-specific output
- quick returns the direct answer first, then only the context needed to
act safely.
Even in quick mode: if the code being touched handles auth, payments, or
PII, flag the trust boundary in one line: don't wait for
hardento find it. - deep →
docs/repo-map.mdwith provenance header (<!-- generated by spelunk on YYYY-MM-DD @ <short-sha>, tree <clean|dirty> -->), sections per the checklist, plus an "Open unknowns" section. Write the file only when it has durable value beyond the current conversation. - teach → layered explanation: what the project is → how one request
flows end-to-end → where things live (with paths) → what the conventions
are → gotchas. Narrative, path-anchored. The request-lifecycle sentence
names real symbols: "Request enters
server.ts:createApp()→ routed viaroutes/index.ts→middleware/auth.tsverifies JWT → handler callsservices/user.ts→ responds." - risk-map → four-quadrant fragility view:
- High churn + high complexity = active friction zone; name files and the type of change that keeps touching them.
- High complexity + low churn = landmine; stable but dangerous when eventually touched.
- Test gaps around trust boundaries = where a silent regression has no coverage (auth, payments, data migrations).
- Cognitive debt = systems where the team's understanding has diverged
from the implementation (look for: stale comments, TODO-in-prod,
code that contradicts the README, recent commits that say "I'm not
sure why this works").
Each item: file path + why it's risky + which skill should own the fix.
Feeds
unslop,harden,sleuth, and planning skills.
Stale-map and contradiction handling
Treat a prior map as an index, not repository truth. Recheck its commit/tree provenance, target package, commands, and the path relevant to the new question. When map and source disagree, source wins; record the invalidated claim and refresh only the affected section. If the mismatch changes the task boundary, return a narrower updated map before planning or editing.
Tool selection / fallback
- Prefer symbol indexes and repository search, then targeted ranged reads.
- Use the bundled inventory script only when its aggregate view answers the question faster.
- Without Git history, omit churn and ownership claims instead of inferring them.
- Prefer a representative executable path and direct symbols over folder-shape narratives. Widen only where a dependency, configuration, or test changes the answer.
Quality gates
- Every factual claim carries a file path and is labeled for its epistemic status where it matters: observed (you read it), inferred (deduced: say from what), or unknown (goes to "Open unknowns"). Risk maps additionally flag churn×size hotspots and auth/money/data flows as risk zones with reasons.
- Commands listed are the ones defined in the repo (scripts entries, CI steps): not generic ecosystem defaults.
- Output contains no detail unrelated to the triggering question or durable map.
- No env var values, secrets, or tokens recorded: names only.
- Every inferred relationship names its supporting observed path; no inference is used as an implementation instruction without confirming evidence.
- Deep maps include target package boundary, provenance, open unknowns, and recheck trigger so a future reader can judge freshness.
Stop conditions
- The triggering question is answered (quick) or the map is written (deep) / explanation delivered (teach).
- Budget cap reached → ship the partial map + "not covered" list.
- Repository turns out to be something else than expected (e.g. a monorepo with 8 apps) → map the relevant app only, note the rest.
- Further scanning will not change answer, risk, or next action → stop; broad inventory is not a quality gate.
- Required runtime or access evidence is unavailable → give a bounded map and precise verification gap.
Output contract
See mode outputs above. In deep mode, end the chat message with the
one-line summary: repo-map: <stack> · <maturity> · <top 2 risks noticed>
, that line is what concierge and planning skills will quote.
Research basis
Read references/research.md when a decision depends on an external standard, a numerical claim, or a fast-moving practice. The ledger records what the source supports, what it does not support, and when to reverify. Read references/discovery-map.md in deep mode or when ecosystem hints are needed. Read references/evidence-protocol.md for monorepos, risk maps, stale maps, or handoff-ready discovery.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies. | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |
| meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要". | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |