socraticode

name	socraticode
description	Codebase Search & Intelligence using SocratiCode. Use when exploring code structure, searching concepts, finding symbol usages, inspecting impact/blast radius before refactoring, tracing execution flows, checking circular dependencies, or searching non-code context artifacts. Automatically checks index status and triggers indexing if the project is not yet indexed.
version	1.1.0
user-invocable	true

Codebase Search & Intelligence (SocratiCode)

Always use SocratiCode MCP tools to explore codebases before reading any files directly.

Initial Prerequisites (On Any Project)

0. Check Index Status First (codebase_status). Before running searches or graph queries on a project, check if it is already indexed.
   • Run codebase_status.
   • If not indexed or missing: Call codebase_index immediately to start background indexing.
   • Poll codebase_status until progress reaches 100% before executing codebase_search.
   • Building the index also automatically constructs the AST dependency graph and symbol call table.

Exploration & Analysis Workflow

1. Start explorations with codebase_search. Hybrid semantic + keyword search (vector + BM25, RRF-fused) runs in a single call.

   • Use broad, conceptual queries for orientation: "how is authentication handled", "database connection setup", "error handling patterns".
   • Use precise queries for symbol lookups: exact function names, constants, type names.
   • Prefer search results to infer which files to read — do not speculatively open files.
   • When to use grep instead: If you already know the exact identifier, error string, or regex pattern, grep/ripgrep is faster and more precise — no semantic gap to bridge. Use codebase_search when you're exploring, asking conceptual questions, or don't know which files to look in.

2. Follow the graph before following imports. Use codebase_graph_query to see what a file imports and what depends on it before diving into its contents. This prevents unnecessary reading of transitive dependencies.

   • Before modifying or deleting a file, check its dependents with codebase_graph_query to understand the blast radius.
   • When planning a refactor, use the graph to identify all affected files before making changes.

3. Use Impact Analysis BEFORE refactoring, renaming, or deleting code. The symbol-level call graph (codebase_impact, codebase_flow, codebase_symbol, codebase_symbols) goes one step deeper than the file graph: it knows which functions and methods call which.

   • codebase_impact answers "what breaks if I change X?" (blast radius — every file that transitively calls into the target).
   • codebase_flow answers "what does this code do?" by tracing forward from an entry point. Call with no entrypoint to discover candidate entry points (auto-detected via orphans, conventional names like main(), framework routes, tests).
   • codebase_symbol gives a 360° view of one function: definition, callers, callees.
   • codebase_symbols lists symbols in a file or searches by name.
   • Always prefer these over reading multiple files when the question is about dependencies between functions, not concepts.

4. Read files only after narrowing down via search. Once search results clearly point to 1–3 files, read only the relevant sections. Never read a file just to find out if it's relevant — search first.

5. Use codebase_graph_circular when debugging unexpected behaviour. Circular dependencies cause subtle runtime issues; check for them proactively. Also run codebase_graph_circular when you notice import-related errors or unexpected initialisation order.

6. Leverage context artifacts for non-code knowledge. Projects can define a .socraticodecontextartifacts.json config to expose database schemas, API specs, infrastructure configs, architecture docs, and other project knowledge that lives outside source code. These artifacts are auto-indexed alongside code during codebase_index and codebase_update.

   • Run codebase_context early to see what artifacts are available.
   • Use codebase_context_search to find specific schemas, endpoints, or configs before asking about database structure or API contracts.
   • If codebase_status shows artifacts are stale, run codebase_context_index to refresh them.

Quick Tool Selection Table

Goal	Tool
Check if current project is indexed	codebase_status
Start indexing an unindexed project	codebase_index $\rightarrow$ poll codebase_status
Understand what a codebase does / where a feature lives	codebase_search (broad query)
Find a specific function, constant, or type	codebase_search (exact name) or grep if exact string
Find exact error messages, log strings, or regex patterns	grep / ripgrep
See what a file imports or what depends on it	codebase_graph_query
Check blast radius before modifying or deleting a file	codebase_impact (symbol-level) or codebase_graph_query (file-level)
What breaks if I change function X?	codebase_impact target=X
What does this entry point actually do?	codebase_flow entrypoint=X
List entry points in this codebase	codebase_flow (no args)
Who calls this function and what does it call?	codebase_symbol name=X
What functions/classes exist in this file?	codebase_symbols file=path
Search for symbols by name across the project	codebase_symbols query=X
Spot architectural problems	codebase_graph_circular, codebase_graph_stats
Visualise module structure	codebase_graph_visualize
Discover non-code project knowledge (schemas, specs, configs)	codebase_context
Find database tables, API endpoints, infra configs	codebase_context_search