Codanna Cursor rule

codanna.md

description	alwaysApply
Codanna code intelligence - semantic search and impact analysis for large codebases	true

Codanna Code Intelligence Integration

Use Codanna to FIND code before reading it, understand relationships, and analyze change impact.

Tool Priority (Codanna Recommended)

Tier 1 (Start here): semantic_search_with_context, analyze_impact
Tier 2 (Specific queries): find_symbol, find_callers, get_calls
Tier 3 (Rarely needed): search_symbols, semantic_search_docs

Default workflow: Start with semantic_search_with_context to get full context upfront, then use analyze_impact for dependencies, then specific tools as needed.

When to Use What Tool

Use Codanna MCP (mcp_codanna_*) for:

• Semantic searches - "Find all places that handle subscription cancellation"
• "How" questions - "How does timezone conversion work?"
• "Where" questions - "Where is tag application handled?"
• Pattern discovery - Finding similar implementations across files
• Understanding relationships - What calls what, what depends on what
• Impact analysis - What breaks if I change this function?

Use grep ONLY for:

• Exact string matches - Finding exact variable names, literal strings
• Known syntax - Finding all uses of a specific function call like apply_tags()

Use read_file for:

• Known file paths - When you already know which file to read

NEVER use codebase_search for WP Fusion:

• Use mcp_codanna_* tools instead - they're indexed with relationships

The key: If you're searching by MEANING (semantic), use Codanna. If you're searching for EXACT text, use grep.

Quick Decision Guide

Most questions → Start with Tier 1:

• "How does X work?" → mcp_codanna_semantic_search_with_context
• "Where is X handled?" → mcp_codanna_semantic_search_with_context
• "Find similar implementations" → mcp_codanna_semantic_search_with_context with lang:php
• "Find all places that do X" → mcp_codanna_semantic_search_with_context
• "What would break if I change X?" → mcp_codanna_analyze_impact

Known symbol names → Use Tier 2:

• "What calls function X?" → mcp_codanna_find_callers
• "What does function X call?" → mcp_codanna_get_calls
• "Find definition of X" → mcp_codanna_find_symbol

Exact text only → Use grep:

• "Find all files containing 'apply_tags('" → grep
• "Find string 'Invalid API key'" → grep

Always run Codanna + Memory in parallel:

Promise.all([
  mcp_memory_recall_memory({ query: "timezone conversion", tags: ["wp-fusion"], limit: 5 }),
  mcp_codanna_semantic_search_with_context({ query: "timezone conversion date handling", limit: 5, lang: "php" })
])

Core Tools (by priority)

Tier 1: Start Here

mcp_codanna_semantic_search_with_context - Search WITH Full Context

Primary tool. Use for most questions. Returns code WITH relationships, callers, dependencies.

mcp_codanna_semantic_search_with_context({
  query: "user authentication and API tokens",
  limit: 3,
  lang: "php"
})

Returns: Symbol + docs + what calls it + what it calls + impact graph.

mcp_codanna_analyze_impact - Complete Dependency Graph

Use before modifying/refactoring.

mcp_codanna_analyze_impact({ symbol_name: "apply_tags" })

Returns: Full dependency tree (calls, type usage, composition).

Tier 2: Specific Queries

mcp_codanna_find_symbol - Exact Symbol Lookup

When you know the exact name.

mcp_codanna_find_symbol({ name: "apply_tags" })

mcp_codanna_find_callers - What Uses This Function

mcp_codanna_find_callers({ function_name: "apply_tags" })

mcp_codanna_get_calls - What This Function Calls

mcp_codanna_get_calls({ function_name: "apply_tags" })

Tier 3: Rarely Needed

mcp_codanna_search_symbols - Fuzzy Name Search

mcp_codanna_search_symbols({ query: "apply", kind: "function" })

mcp_codanna_semantic_search_docs - Search Without Context

Only use if context isn't needed (rare).

mcp_codanna_semantic_search_docs({ query: "apply tags", lang: "php" })

Workflow Example

User asks: "How do we handle MemberPress subscription cancellations?"

// 1. Start with Tier 1: Get full context upfront
mcp_codanna_semantic_search_with_context({
  query: "memberpress subscription cancellation lifecycle",
  limit: 3,
  lang: "php"
})

// 2. If modifying code, analyze impact
mcp_codanna_analyze_impact({ symbol_name: "cancel_subscription" })

// 3. Read specific files found
read_file("includes/integrations/memberpress/class-memberpress.php")

// 4. If needed, get specific callers
mcp_codanna_find_callers({ function_name: "cancel_subscription" })

Best Practices

1. Start with Tier 1 - Default to semantic_search_with_context for most questions
2. Get context upfront - Don't search without context, then get context separately
3. Use language filters - Add lang: "php" to reduce noise
4. Check impact before changes - Always run analyze_impact before modifying core functions
5. Store discoveries - Save patterns in memory for future reference
6. Parallel execution - Run memory + Codanna together for comprehensive context
7. Natural queries - Use natural language, not code syntax

Anti-Patterns

• ❌ Use semantic_search_docs then semantic_search_with_context → ✅ Start with semantic_search_with_context
• ❌ Read 20 files to find code → ✅ Use semantic_search_with_context first
• ❌ Use grep for semantic searches ("find all X that handle Y") → ✅ Use Codanna vector search
• ❌ Use codebase_search for WP Fusion → ✅ Use mcp_codanna_* tools (indexed)
• ❌ Change core function without checking → ✅ analyze_impact then modify
• ❌ Use Codanna for exact text matches → ✅ Use grep for literal strings

Error Handling

If Codanna fails:

• No results: Refine query, try different terms, remove filters
• Too many results: Add lang: "php", increase specificity, use kind filter
• Service unavailable: Fall back to grep/file reading

Codanna enhances discovery but should never block progress.