Imported from denfry/codebase-index (src/codebase_index/skill_template/SKILL.md). Install upstream with npx skills add denfry/codebase-index --skill skill_template. Copyright stays with the author.

Codebase Index

Use the local index before reading repository files.

The operating principle is Find → Trace → Verify → Predict:

• Find the implementation with ranked retrieval.
• Trace behavior through definitions, callers, dependencies, and paths.
• Verify that evidence you already hold is still true before relying on it.
• Predict change impact while preserving an explicit evidence trail.

Route the question

Use search --mode symbol for exact symbol work, --mode fts for text and error messages, and the default hybrid mode for mixed questions. Use pure vector mode only when embeddings are enabled and exact vocabulary is unknown.

Read references/commands.md only when command options or routing remain unclear.

Evidence protocol

1. Pick one session tag for this conversation (for example auth-fix-1) and pass --session <tag> to every search and explain.
2. Run the best-matching command with --json.
3. Check index before trusting the payload:
   • missing → run codebase-index index, then repeat;
   • stale with fewer than 20 changed files → run codebase-index update;
   • stale with 20 or more changed files → run codebase-index index;
   • fresh → continue.
4. Start with ranks 1–3. Read only recommended_reads line ranges.
5. Trace one additional hop only when the question requires behavior, ownership, or impact.
6. Before answering or editing from evidence gathered earlier in the task, run codebase-index verify --session <tag> --json and reread anything whose state is not valid or relocated.
7. Answer with file:line evidence and state uncertainty explicitly.

Do not open whole files when a line range is available. A snippet may already be sufficient. skeletonized: true means the response intentionally folded unrelated body lines; read the supplied range when the missing body matters.

Evidence memory

• reused: true with snippet: null — this session already received that exact text and its source is unchanged. Use your earlier copy; if you can no longer see it, Read the range.
• memory.invalidated — evidence this session received has changed since. Treat your earlier copy as wrong and reread before relying on it.
• stale: true — the index is older than the file. Run codebase-index update or Read the range.
• A tag belongs to one context. Never give it to a subagent or another conversation. Start a new tag after the context is cleared or compacted, or whenever earlier snippets are no longer visible to you.

Verdict states and citing evidence in notes: references/memory.md.

Confidence contract

• high — answer from the indexed evidence.
• medium — read the recommended ranges and confirm the key claim with one targeted lookup if necessary.
• low or no results — follow fallback_suggestions, then use a narrow Grep/Glob fallback.

On refs and impact, inspect coverage. If coverage.partial is true, an empty result is inconclusive; confirm with targeted Grep before saying that nothing references the target.

Edges carry confidence:

• extracted — exact parser evidence;
• inferred — heuristic resolution;
• ambiguous — unresolved or non-unique.

Never present an inferred or ambiguous chain as certain.

Answer contract

Structure repository answers around:

1. Answer — the direct conclusion.
2. Evidence — the minimum supporting file:line references.
3. Confidence — only when evidence is partial, inferred, stale, or missing.
4. Next check — only when another check would materially reduce uncertainty.

Do not narrate every search step. Do not claim absence from a partial graph. Do not replace evidence with a generated HTML graph.

For payload fields and failure handling, read references/response-contract.md.