Code Evidence

Code Evidence Retrieval

Standalone skill for searching a code repository using natural language queries. Retrieves ranked code snippets grounded in actual source code — function signatures, class definitions, configuration blocks, and documentation.

Uses hybrid search: BM25 for exact keyword matches + vector embeddings for semantic similarity. The index is built once per repo using AST chunking (tree-sitter) and cached for subsequent queries.

Prerequisites

• code-finder Python package. Install once with python3 -m pip install code-finder, or let the skill auto-install via uv run --with code-finder (requires uv: brew install uv on macOS, or see https://docs.astral.sh/uv/getting-started/installation/)
• Wrapper scripts in ${CLAUDE_SKILL_DIR}/scripts/ call the code-finder Python API directly (no CLI entry point required):
• find_evidence.py — hybrid search for code snippets matching natural language queries
• grounded_review.py — validate document claims against source code
• api_surface.py — extract public API surface (classes, functions, methods) via AST parsing

Arguments

• --repo — Path to the repository to search (required)
• --query "" — Natural language search query (single query mode)
• --queries-file — Path to a JSON file with batch queries (use instead of --query for multiple searches in one invocation). Schema: [{"query": "...", "limit": N, "filter_paths": ["dir1", "dir2"]}, ...]
• --filter-paths — Comma-separated directory prefixes to scope results (e.g., src/auth,src/config). Single query mode only. Resolved relative to the repo root.
• --limit — Max results to return (default: 5). In batch mode, acts as default limit per query (overridden by per-entry limit).
• --reindex — Force re-indexing even if a cached index exists (in batch mode, applied to first query only)

Execution

1. Parse arguments

Extract --repo, --query, and optional flags from the args string.

Validate:

• Verify the repo path exists. If not, STOP with error: "Repo path does not exist: "
• Verify the wrapper script exists. If not, STOP with error: "find_evidence.py script not found."

2. Run evidence retrieval

First, check if code-finder is already installed:

python3 -c "import claude_context" 2>/dev/null && echo "INSTALLED" || echo "NOT_INSTALLED"

Use the appropriate command based on the result. If INSTALLED, run directly (avoids re-downloading ~1GB of ML dependencies). If NOT_INSTALLED, prefix with uv run --with code-finder.

Direct (code-finder installed):

python3 ${CLAUDE_SKILL_DIR}/scripts/find_evidence.py \
  --repo "" \
  --query "" \
  --limit 

Fallback (via uv):

uv run --with code-finder python3 ${CLAUDE_SKILL_DIR}/scripts/find_evidence.py \
  --repo "" \
  --query "" \
  --limit 

If --filter-paths was provided, add --filter-paths to the command.

If --reindex was provided, add --reindex to the command.

3. Present results

Parse the JSON output and present results to the user in a readable format:

## Results for: ""

**Repository:** 
**Results:** 

### 1. :- — `` ()
   Score:  (vector: , BM25: )

   ```
   
   ```

### 2. ...

Include the full content of each result so the user can see the actual code. If a result has a signature or docstring, show those prominently.

Notes

• First run on a repo takes a few seconds to a few minutes depending on repo size (AST chunking + embeddings)
• Subsequent runs reuse the cached index at {repo}/.vibe2doc/index.db
• Use --reindex after significant code changes
• Default index exclusions skip archive/, vendor/, node_modules/, docs/generated/, .vibe2doc/, and other non-source directories
• Supports Go, Python, JavaScript, and TypeScript via tree-sitter grammars
• --filter-paths is useful for scoping to specific modules (e.g., --filter-paths src/auth to search only the auth module)

Examples

Search an entire repo:

Skill: code-evidence, args: "--repo /path/to/repo --query \"how does authentication work\""

Search scoped to specific directories:

Skill: code-evidence, args: "--repo /path/to/repo --query \"reconciler builder pattern\" --filter-paths internal/controller,pkg/reconciler"

Re-index after pulling new changes:

Skill: code-evidence, args: "--repo /path/to/repo --query \"new feature\" --reindex"

---

Grounded Review

Validates claims in a draft document against source code. For each claim extracted from the document, returns a verdict (supported, partially_supported, unsupported, or no_evidence_found) with supporting code evidence.

Wrapper script: ${CLAUDE_SKILL_DIR}/scripts/grounded_review.py

Arguments

• --repo — Path to the repository (required)
• --draft — Path to a single draft document (single mode)
• --drafts-file — Path to JSON file with batch drafts (use instead of --draft for multiple documents in one invocation). Schema: [{"draft": "/path/to/file.adoc", "max_evidence": 5}, ...]
• --max-evidence — Max evidence snippets per claim (default: 5)
• --reindex — Force re-indexing (applied to first draft only in batch mode)

Execution

Check if code-finder is installed, then run:

Direct (code-finder installed):

python3 ${CLAUDE_SKILL_DIR}/scripts/grounded_review.py \
  --repo "" \
  --draft "" > /tmp/grounded-review.json

Batch mode:

python3 ${CLAUDE_SKILL_DIR}/scripts/grounded_review.py \
  --repo "" \
  --drafts-file drafts.json \
  --reindex > /tmp/grounded-review.json

Fallback (via uv): prefix with uv run --with code-finder.

Output

Single mode returns a dict with per-claim results. Batch mode returns an array of {"draft": "", "result": {...}}.

Each claim includes:

• claim_id, text — the extracted claim from the document
• verdict — supported, partially_supported, unsupported, or no_evidence_found
• confidence — 0.0–1.0 relevance score
• evidence — array of {file_path, start_line, end_line, chunk_type, chunk_name, relevance_score, content_snippet}

---

API Surface Extraction

Extracts the public API surface from source files using AST parsing. Returns classes, functions, and methods with their signatures and line ranges.

Wrapper script: ${CLAUDE_SKILL_DIR}/scripts/api_surface.py

Arguments

• --target — Path to a file or directory to analyze (required)
• --languages — Comma-separated language filter (e.g., python,go,typescript)
• --include-private — Include private names (prefixed with _)
• --no-docstrings — Exclude docstrings from output

Execution

Check if code-finder is installed, then run:

python3 ${CLAUDE_SKILL_DIR}/scripts/api_surface.py \
  --target "" > /tmp/api-surface.json

Fallback (via uv): prefix with uv run --with code-finder.

Output

Returns a dict with:

• api_surface — per-file map of entities (classes, functions, methods with signatures and line ranges)
• totalentities, filesprocessed, fileswithapi — summary counts

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: abhatt-rh
• Source: abhatt-rh/redhat-docs-agent-tools
• License: Apache-2.0
• Homepage: https://redhat-documentation.github.io/redhat-docs-agent-tools/

Install and usage instructions live in the source repository linked above.