developer-detective
⚡ PRIMARY TOOL for: 'how does X work', 'find implementation of', 'trace data flow', 'where is X defined', 'audit integrations', 'find all usages'. Uses claudemem v0.3.0 AST with callers/callees analysis. GREP/FIND/GLOB ARE FORBIDDEN.
$ インストール
git clone https://github.com/MadAppGang/claude-code /tmp/claude-code && cp -r /tmp/claude-code/plugins/code-analysis/skills/developer-detective ~/.claude/skills/claude-code// tip: Run this command in your terminal to install the skill
name: developer-detective description: "⚡ PRIMARY TOOL for: 'how does X work', 'find implementation of', 'trace data flow', 'where is X defined', 'audit integrations', 'find all usages'. Uses claudemem v0.3.0 AST with callers/callees analysis. GREP/FIND/GLOB ARE FORBIDDEN." allowed-tools: Bash, Task, Read, AskUserQuestion
⛔⛔⛔ CRITICAL: AST STRUCTURAL ANALYSIS ONLY ⛔⛔⛔
╔══════════════════════════════════════════════════════════════════════════════╗
║ ║
║ 🧠 THIS SKILL USES claudemem v0.3.0 AST ANALYSIS EXCLUSIVELY ║
║ ║
║ ❌ GREP IS FORBIDDEN ║
║ ❌ FIND IS FORBIDDEN ║
║ ❌ GLOB IS FORBIDDEN ║
║ ║
║ ✅ claudemem --agent callers <name> FOR USAGE ANALYSIS ║
║ ✅ claudemem --agent callees <name> FOR DEPENDENCY TRACING ║
║ ✅ claudemem --agent context <name> FOR FULL UNDERSTANDING ║
║ ║
║ ⭐ v0.3.0: callers/callees show exact data flow and dependencies ║
║ ║
╚══════════════════════════════════════════════════════════════════════════════╝
Developer Detective Skill
Version: 3.3.0 Role: Software Developer Purpose: Implementation investigation using AST callers/callees and impact analysis
Role Context
You are investigating this codebase as a Software Developer. Your focus is on:
- Implementation details - How code actually works
- Data flow - How data moves through the system (via callees)
- Usage patterns - How code is used (via callers)
- Dependencies - What a function needs to work
- Impact analysis - What breaks if you change something
Why callers/callees is Perfect for Development
The callers and callees commands show you:
- callers = Every place that calls this code (impact of changes)
- callees = Every function this code calls (its dependencies)
- Exact file:line = Precise locations for reading/editing
- Call kinds = call, import, extends, implements
Developer-Focused Commands (v0.3.0)
Find Implementation
# Find where a function is defined
claudemem --agent symbol processPayment
# Get full context with callers and callees
claudemem --agent context processPayment```
### Trace Data Flow
```bash
# What does this function call? (data flows OUT)
claudemem --agent callees processPayment
# Follow the chain
claudemem --agent callees validateCardclaudemem --agent callees chargeStripe```
### Find All Usages
```bash
# Who calls this function? (usage patterns)
claudemem --agent callers processPayment
# This shows EVERY place that uses this code
Impact Analysis (v0.4.0+ Required)
# Before modifying ANY code, check full impact
claudemem --agent impact functionToChange
# Output shows ALL transitive callers:
# direct_callers:
# - LoginController.authenticate:34
# - SessionMiddleware.validate:12
# transitive_callers (depth 2):
# - AppRouter.handleRequest:45
# - TestSuite.runAuth:89
Why impact matters:
callersshows only direct callers (1 level)impactshows ALL transitive callers (full tree)- Critical for refactoring decisions
Handling Empty Results:
IMPACT=$(claudemem --agent impact functionToChange)
if echo "$IMPACT" | grep -q "No callers"; then
echo "No callers found. This is either:"
echo " 1. An entry point (API handler, main function) - expected"
echo " 2. Dead code - verify with: claudemem dead-code"
echo " 3. Dynamically called - check for import(), reflection"
fi
Impact Analysis (BEFORE Modifying)
# Quick check - direct callers only (v0.3.0)
claudemem --agent callers functionToChange
# Deep check - ALL transitive callers (v0.4.0+ Required)
IMPACT=$(claudemem --agent impact functionToChange)
# Handle results
if [ -z "$IMPACT" ] || echo "$IMPACT" | grep -q "No callers"; then
echo "No static callers found - verify dynamic usage patterns"
else
echo "$IMPACT"
echo ""
echo "This tells you:"
echo "- Direct callers (immediate impact)"
echo "- Transitive callers (ripple effects)"
echo "- Grouped by file (for systematic updates)"
fi
Understanding Complex Code
# Get full picture: definition + callers + callees
claudemem --agent context complexFunction```
## PHASE 0: MANDATORY SETUP
### Step 1: Verify claudemem v0.3.0
```bash
which claudemem && claudemem --version
# Must be 0.3.0+
Step 2: If Not Installed → STOP
Use AskUserQuestion (see ultrathink-detective for template)
Step 3: Check Index Status
# Check claudemem installation and index
claudemem --version && ls -la .claudemem/index.db 2>/dev/null
Step 3.5: Check Index Freshness
Before proceeding with investigation, verify the index is current:
# First check if index exists
if [ ! -d ".claudemem" ] || [ ! -f ".claudemem/index.db" ]; then
# Use AskUserQuestion to prompt for index creation
# Options: [1] Create index now (Recommended), [2] Cancel investigation
exit 1
fi
# Count files modified since last index
STALE_COUNT=$(find . -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" -o -name "*.py" -o -name "*.go" -o -name "*.rs" \) \
-newer .claudemem/index.db 2>/dev/null | grep -v "node_modules" | grep -v ".git" | grep -v "dist" | grep -v "build" | wc -l)
STALE_COUNT=$((STALE_COUNT + 0)) # Normalize to integer
if [ "$STALE_COUNT" -gt 0 ]; then
# Get index time with explicit platform detection
if [[ "$OSTYPE" == "darwin"* ]]; then
INDEX_TIME=$(stat -f "%Sm" -t "%Y-%m-%d %H:%M" .claudemem/index.db 2>/dev/null)
else
INDEX_TIME=$(stat -c "%y" .claudemem/index.db 2>/dev/null | cut -d'.' -f1)
fi
INDEX_TIME=${INDEX_TIME:-"unknown time"}
# Get sample of stale files
STALE_SAMPLE=$(find . -type f \( -name "*.ts" -o -name "*.tsx" \) \
-newer .claudemem/index.db 2>/dev/null | grep -v "node_modules" | grep -v ".git" | head -5)
# Use AskUserQuestion (see template in ultrathink-detective)
fi
Step 4: Index if Needed
claudemem index
Workflow: Implementation Investigation (v0.3.0)
Phase 1: Map the Area
# Get overview of the feature area
claudemem --agent map "payment processing"```
### Phase 2: Find the Entry Point
```bash
# Locate the main function (highest PageRank in area)
claudemem --agent symbol PaymentService```
### Phase 3: Trace the Flow
```bash
# What does PaymentService call?
claudemem --agent callees PaymentService
# For each major callee, trace further
claudemem --agent callees validatePaymentclaudemem --agent callees processChargeclaudemem --agent callees saveTransaction```
### Phase 4: Understand Usage
```bash
# Who uses PaymentService?
claudemem --agent callers PaymentService
# This shows the entry points
Phase 5: Read Specific Code
# Now read ONLY the relevant file:line ranges from results
# DON'T read whole files
Output Format: Implementation Report
1. Symbol Overview
┌─────────────────────────────────────────────────────────┐
│ IMPLEMENTATION ANALYSIS │
├─────────────────────────────────────────────────────────┤
│ Symbol: processPayment │
│ Location: src/services/payment.ts:45-89 │
│ Kind: function │
│ PageRank: 0.034 │
│ Search Method: claudemem v0.3.0 (AST analysis) │
└─────────────────────────────────────────────────────────┘
2. Data Flow (Callees)
processPayment
├── validateCard (src/validators/card.ts:12)
├── getCustomer (src/services/customer.ts:34)
├── chargeStripe (src/integrations/stripe.ts:56)
│ └── stripe.charges.create (external)
└── saveTransaction (src/repositories/transaction.ts:78)
└── database.insert (src/db/index.ts:23)
3. Usage (Callers)
processPayment is called by:
├── CheckoutController.submit (src/controllers/checkout.ts:45)
├── SubscriptionService.renew (src/services/subscription.ts:89)
└── RetryQueue.processPayment (src/workers/retry.ts:23)
4. Impact Analysis
⚠️ IMPACT: Changing processPayment will affect:
- 3 direct callers (shown above)
- Checkout flow (user-facing)
- Subscription renewals (automated)
- Payment retry logic (background)
Scenarios
Scenario: "How does X work?"
# Step 1: Find X
claudemem --agent symbol X
# Step 2: See what X does
claudemem --agent callees X
# Step 3: See how X is used
claudemem --agent callers X
# Step 4: Read the specific code
# Use Read tool on exact file:line from results
Scenario: Refactoring
# Step 1: Find ALL usages (callers)
claudemem --agent callers oldFunction
# Step 2: Document each caller location
# Step 3: Update each caller systematically
Scenario: Adding to Existing Code
# Step 1: Find where to add
claudemem --agent symbol targetModule
# Step 2: Understand dependencies
claudemem --agent callees targetModule
# Step 3: Check existing patterns
claudemem --agent callers targetModule```
## Result Validation Pattern
After EVERY claudemem command, validate results:
### Symbol/Callers Validation
When tracing implementation:
```bash
# Find symbol
SYMBOL=$(claudemem --agent symbol PaymentService)
EXIT_CODE=$?
if [ "$EXIT_CODE" -ne 0 ] || [ -z "$SYMBOL" ] || echo "$SYMBOL" | grep -qi "not found\|error"; then
# Symbol doesn't exist, typo, or index issue
# Diagnose index health
DIAGNOSIS=$(claudemem --version && ls -la .claudemem/index.db 2>&1)
# Use AskUserQuestion with suggestions:
# [1] Reindex, [2] Try different name, [3] Cancel
fi
# Check callers
CALLERS=$(claudemem --agent callers PaymentService)
# 0 callers is valid (entry point or unused)
# But error message is not
if echo "$CALLERS" | grep -qi "error\|failed"; then
# Use AskUserQuestion
fi
Empty/Irrelevant Results
RESULTS=$(claudemem --agent callees FunctionName)
# Validate relevance
# Extract keywords from the user's investigation query
# Example: QUERY="how does auth work" → KEYWORDS="auth work authentication"
# The orchestrating agent must populate KEYWORDS before this check
MATCH_COUNT=0
for kw in $KEYWORDS; do
if echo "$RESULTS" | grep -qi "$kw"; then
MATCH_COUNT=$((MATCH_COUNT + 1))
fi
done
if [ "$MATCH_COUNT" -eq 0 ]; then
# Results don't match expected dependencies
# Use AskUserQuestion: Reindex, Different query, or Cancel
fi
FALLBACK PROTOCOL
CRITICAL: Never use grep/find/Glob without explicit user approval.
If claudemem fails or returns irrelevant results:
- STOP - Do not silently switch tools
- DIAGNOSE - Run
claudemem status - REPORT - Tell user what happened
- ASK - Use AskUserQuestion for next steps
// Fallback options (in order of preference)
AskUserQuestion({
questions: [{
question: "claudemem [command] failed or returned no relevant results. How should I proceed?",
header: "Investigation Issue",
multiSelect: false,
options: [
{ label: "Reindex codebase", description: "Run claudemem index (~1-2 min)" },
{ label: "Try different query", description: "Rephrase the search" },
{ label: "Use grep (not recommended)", description: "Traditional search - loses call graph analysis" },
{ label: "Cancel", description: "Stop investigation" }
]
}]
})
See ultrathink-detective skill for complete Fallback Protocol documentation.
Anti-Patterns
| Anti-Pattern | Why Wrong | Correct Approach |
|---|---|---|
grep -r "function" | No call relationships | claudemem --agent callees func |
| Modify without callers | Breaking changes | ALWAYS check callers first |
| Read whole files | Token waste | Read specific file:line from results |
| Guess dependencies | Miss connections | Use callees for exact deps |
cmd | head/tail | Hides callers/callees | Use full output or --tokens |
Output Truncation Warning
╔══════════════════════════════════════════════════════════════════════════════╗ ║ ║ ║ ❌ Anti-Pattern 7: Truncating Claudemem Output ║ ║ ║ ║ FORBIDDEN (any form of output truncation): ║ ║ → BAD: claudemem --agent map "query" | head -80 ║ ║ → BAD: claudemem --agent callers X | tail -50 ║ ║ → BAD: claudemem --agent search "x" | grep -m 10 "y" ║ ║ → BAD: claudemem --agent map "q" | awk 'NR <= 50' ║ ║ → BAD: claudemem --agent callers X | sed '50q' ║ ║ → BAD: claudemem --agent search "x" | sort | head -20 ║ ║ → BAD: claudemem --agent map "q" | grep "pattern" | head -20 ║ ║ ║ ║ CORRECT (use full output or built-in limits): ║ ║ → GOOD: claudemem --agent map "query" ║ ║ → GOOD: claudemem --agent search "x" -n 10 ║ ║ → GOOD: claudemem --agent map "q" --tokens 2000 ║ ║ → GOOD: claudemem --agent search "x" --page-size 20 --page 1 ║ ║ → GOOD: claudemem --agent context Func --max-depth 3 ║ ║ ║ ║ WHY: Output is pre-optimized; truncation hides critical results ║ ║ ║ ╚══════════════════════════════════════════════════════════════════════════════╝
Feedback Reporting (v0.8.0+)
After completing investigation, report search feedback to improve future results.
When to Report
Report feedback ONLY if you used the search command during investigation:
| Result Type | Mark As | Reason |
|---|---|---|
| Read and used | Helpful | Contributed to investigation |
| Read but irrelevant | Unhelpful | False positive |
| Skipped after preview | Unhelpful | Not relevant to query |
| Never read | (Don't track) | Can't evaluate |
Feedback Pattern
# Track during investigation
SEARCH_QUERY="your original query"
HELPFUL_IDS=""
UNHELPFUL_IDS=""
# When reading a helpful result
HELPFUL_IDS="$HELPFUL_IDS,$result_id"
# When reading an unhelpful result
UNHELPFUL_IDS="$UNHELPFUL_IDS,$result_id"
# Report at end of investigation (v0.8.0+ only)
if claudemem feedback --help 2>&1 | grep -qi "feedback"; then
timeout 5 claudemem feedback \
--query "$SEARCH_QUERY" \
--helpful "${HELPFUL_IDS#,}" \
--unhelpful "${UNHELPFUL_IDS#,}" 2>/dev/null || true
fi
Output Update
Include in investigation report:
Search Feedback: [X helpful, Y unhelpful] - Submitted (v0.8.0+)
Notes
callersis essential before any modification - Know your impactcalleestraces data flow - Follow the execution pathcontextgives complete picture - Symbol + callers + callees- Always read specific file:line ranges, not whole files
- Works best with TypeScript, Go, Python, Rust codebases
Maintained by: MadAppGang Plugin: code-analysis v2.7.0 Last Updated: December 2025 (v3.3.0 - Cross-platform compatibility, inline templates, improved validation)
Repository
