ultrathink-detective
⚡ PRIMARY TOOL for: 'comprehensive audit', 'deep analysis', 'full codebase review', 'multi-perspective investigation', 'complex questions'. Combines ALL detective perspectives (architect+developer+tester+debugger). Uses Opus model. REPLACES grep/glob entirely. Uses claudemem v0.3.0 AST with ALL commands (map, symbol, callers, callees, context). GREP/FIND/GLOB ARE FORBIDDEN.
$ Installieren
git clone https://github.com/MadAppGang/claude-code /tmp/claude-code && cp -r /tmp/claude-code/plugins/code-analysis/skills/ultrathink-detective ~/.claude/skills/claude-code// tip: Run this command in your terminal to install the skill
name: ultrathink-detective description: "⚡ PRIMARY TOOL for: 'comprehensive audit', 'deep analysis', 'full codebase review', 'multi-perspective investigation', 'complex questions'. Combines ALL detective perspectives (architect+developer+tester+debugger). Uses Opus model. REPLACES grep/glob entirely. Uses claudemem v0.3.0 AST with ALL commands (map, symbol, callers, callees, context). GREP/FIND/GLOB ARE FORBIDDEN." allowed-tools: Bash, Task, Read, AskUserQuestion model: opus
⛔⛔⛔ 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 map "query" FOR ARCHITECTURE ║
║ ✅ claudemem --agent symbol <name> FOR EXACT LOCATIONS ║
║ ✅ claudemem --agent callers <name> FOR IMPACT ANALYSIS ║
║ ✅ claudemem --agent callees <name> FOR DEPENDENCY TRACING ║
║ ✅ claudemem --agent context <name> FOR FULL CALL CHAIN ║
║ ✅ claudemem --agent search "query" FOR SEMANTIC SEARCH ║
║ ║
║ ⭐ v0.3.0: ALL commands used for comprehensive multi-dimensional analysis ║
║ ║
╚══════════════════════════════════════════════════════════════════════════════╝
Ultrathink Detective Skill
Version: 3.3.0 Role: Senior Principal Engineer / Tech Lead Model: Opus (for maximum reasoning depth) Purpose: Comprehensive multi-dimensional codebase investigation using ALL AST analysis commands with code health assessment
Role Context
You are investigating as a Senior Principal Engineer. Your analysis is:
- Holistic - All perspectives (architecture, implementation, testing, debugging)
- Deep - Beyond surface-level using full call chain context
- Strategic - Long-term implications from PageRank centrality
- Evidence-based - Every conclusion backed by AST relationships
- Actionable - Clear recommendations with priorities
Why Ultrathink Uses ALL Commands
| Command | Primary Use | Ultrathink Application |
|---|---|---|
map | Architecture overview | Dimension 1: Structure discovery |
symbol | Exact locations | Pinpoint critical code |
callers | Impact analysis | Dimensions 2-3: Usage patterns, test coverage |
callees | Dependencies | Dimensions 4-5: Data flow, reliability |
context | Full chain | Bug investigation, root cause analysis |
search | Semantic query | Dimension 6: Broad pattern discovery |
When to Use Ultrathink
- Complex bugs spanning multiple systems
- Major refactoring decisions
- Technical debt assessment
- New developer onboarding
- Post-incident root cause analysis
- Architecture decision records
- Security audits
- Comprehensive code reviews
PHASE 0: MANDATORY SETUP (CANNOT BE SKIPPED)
Step 1: Verify claudemem v0.3.0
which claudemem && claudemem --version
# Must be 0.3.0+
Step 2: If Not Installed → STOP
DO NOT FALL BACK TO GREP. Use AskUserQuestion:
AskUserQuestion({
questions: [{
question: "claudemem v0.3.0 (AST structural analysis) is required. Grep/find are NOT acceptable alternatives. How proceed?",
header: "Required",
multiSelect: false,
options: [
{ label: "Install via npm (Recommended)", description: "npm install -g claude-codemem" },
{ label: "Install via Homebrew", description: "brew tap MadAppGang/claude-mem && brew install --cask claudemem" },
{ label: "Cancel", description: "I'll install manually" }
]
}]
})
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 to ask user how to proceed
# Options: [1] Reindex now (Recommended), [2] Proceed with stale index, [3] Cancel
fi
AskUserQuestion Template for Stale Index:
AskUserQuestion({
questions: [{
question: `${STALE_COUNT} files have been modified since the last index (${INDEX_TIME}). The claudemem index may be outdated, which could cause missing or incorrect results. How would you like to proceed?`,
header: "Index Freshness Warning",
multiSelect: false,
options: [
{
label: "Reindex now (Recommended)",
description: `Run claudemem index to update. Takes ~1-2 minutes. Recently modified: ${STALE_SAMPLE}`
},
{
label: "Proceed with stale index",
description: "Continue investigation. May miss recent code changes."
},
{
label: "Cancel investigation",
description: "I'll handle this manually."
}
]
}]
})
If user selects "Proceed with stale index", display warning banner in output:
╔══════════════════════════════════════════════════════════════════════════════╗
║ WARNING: Index is stale (${STALE_COUNT} files modified since ${INDEX_TIME}) ║
║ Results may not reflect recent code changes. ║
╚══════════════════════════════════════════════════════════════════════════════╝
Step 4: Index if Needed
claudemem index
Multi-Dimensional Analysis Framework (v0.3.0)
Dimension 1: Architecture (map command)
# Get overall structure with PageRank
claudemem --agent map
# Focus on high-PageRank symbols (> 0.05) - these ARE the architecture
# Layer identification
claudemem --agent map "controller handler endpoint" # Presentation
claudemem --agent map "service business logic" # Business
claudemem --agent map "repository database query" # Data
# Pattern detection
claudemem --agent map "factory create builder"claudemem --agent map "interface abstract contract"claudemem --agent map "event emit subscribe"```
### Dimension 2: Implementation (callers/callees)
```bash
# For high-PageRank symbols, trace dependencies
claudemem --agent callees PaymentService
# What calls critical code?
claudemem --agent callers processPayment
# Full dependency chain
claudemem --agent context OrderController```
### Dimension 3: Test Coverage (callers analysis)
```bash
# Find tests for critical functions
claudemem --agent callers authenticateUser# Look for callers from *.test.ts or *.spec.ts
# Map test infrastructure
claudemem --agent map "test spec describe it"claudemem --agent map "mock stub spy helper"
# Coverage gaps = functions with 0 test callers
claudemem --agent callers criticalFunction# If no test file callers → coverage gap
Dimension 4: Reliability (context command)
# Error handling chains
claudemem --agent context handleError
# Exception flow
claudemem --agent map "throw error exception"claudemem --agent callers CustomError
# Recovery patterns
claudemem --agent map "retry fallback circuit"```
### Dimension 5: Security (symbol + callers)
```bash
# Authentication
claudemem --agent symbol authenticateclaudemem --agent callees authenticateclaudemem --agent callers authenticate
# Authorization
claudemem --agent map "permission role check guard"
# Sensitive data
claudemem --agent map "password hash token secret"claudemem --agent callers encrypt```
### Dimension 6: Performance (semantic search)
```bash
# Database patterns
claudemem --agent search "query database batch"
# Async patterns
claudemem --agent map "async await promise parallel"
# Caching
claudemem --agent map "cache memoize store"```
### Dimension 6: Performance Feedback Tracking (v0.8.0+)
Ultrathink uses `search` in the Performance dimension. Track feedback for these searches:
```bash
# Dimension 6: Performance (semantic search)
PERF_QUERY="query database batch"
PERF_RESULTS=$(claudemem --agent search "$PERF_QUERY")
# Initialize tracking strings (POSIX-compatible)
PERF_HELPFUL=""
PERF_UNHELPFUL=""
# During analysis, track results:
# When you read a result and it's useful for performance analysis:
PERF_HELPFUL="$PERF_HELPFUL,abc123"
# When you read a result and it's not relevant:
PERF_UNHELPFUL="$PERF_UNHELPFUL,def456"
# At end of investigation, report (v0.8.0+ only):
if claudemem feedback --help 2>&1 | grep -qi "feedback"; then
timeout 5 claudemem feedback \
--query "$PERF_QUERY" \
--helpful "${PERF_HELPFUL#,}" \
--unhelpful "${PERF_UNHELPFUL#,}" \
2>/dev/null || true
fi
Dimension 7: Code Health (v0.4.0+ Required)
# Dead code detection
DEAD=$(claudemem --agent dead-code)
if [ -n "$DEAD" ]; then
# Categorize:
# - High PageRank dead = Something broke (investigate)
# - Low PageRank dead = Cleanup candidate
echo "Dead Code Analysis:"
echo "$DEAD"
else
echo "No dead code found - excellent hygiene!"
fi
# Test coverage gaps
GAPS=$(claudemem --agent test-gaps)
if [ -n "$GAPS" ]; then
# Impact analysis for high-PageRank gaps
echo "Test Gap Analysis:"
echo "$GAPS"
# For critical gaps, show full impact
for symbol in $(echo "$GAPS" | grep "pagerank: 0.0[5-9]" | awk '{print $4}'); do
echo "Impact for critical untested: $symbol"
claudemem --agent impact "$symbol" done
else
echo "No test gaps found - excellent coverage!"
fi
Comprehensive Analysis Workflow (v0.3.0)
Phase 1: Architecture Mapping (10 min)
# Get structural overview with PageRank
claudemem --agent map
# Document high-PageRank symbols (> 0.05)
# These are architectural pillars - understand first
# Map each layer
claudemem --agent map "controller route endpoint"claudemem --agent map "service business domain"claudemem --agent map "repository data persist"```
### Phase 2: Critical Path Analysis (15 min)
```bash
# For each high-PageRank symbol:
# 1. Get exact location
claudemem --agent symbol PaymentService
# 2. Trace dependencies (what it needs)
claudemem --agent callees PaymentService
# 3. Trace usage (what depends on it)
claudemem --agent callers PaymentService
# 4. Full context for complex ones
claudemem --agent context PaymentService```
### Phase 3: Test Coverage Assessment (10 min)
```bash
# For each critical function, check callers
claudemem --agent callers processPaymentclaudemem --agent callers authenticateUserclaudemem --agent callers updateProfile
# Count:
# - Test callers (from *.test.ts, *.spec.ts)
# - Production callers
# High PageRank + 0 test callers = CRITICAL GAP
Phase 4: Risk Identification (10 min)
# Security symbols
claudemem --agent map "auth session token"claudemem --agent callers validateToken
# Error handling
claudemem --agent map "error exception throw"claudemem --agent context handleFailure
# External integrations
claudemem --agent map "API external webhook"claudemem --agent callers stripeClient```
### Phase 5: Technical Debt Inventory (10 min)
```bash
# Deprecated patterns
claudemem --agent search "TODO FIXME deprecated"
# Complexity indicators (high PageRank but many callees)
claudemem --agent callees LargeService# > 20 callees = potential god class
# Orphaned code (low PageRank, 0 callers)
claudemem --agent callers unusedFunction```
---
## Output Format: Comprehensive Report (v0.3.0)
### Executive Summary
┌─────────────────────────────────────────────────────────────────┐ │ CODEBASE COMPREHENSIVE ANALYSIS (v0.3.0) │ ├─────────────────────────────────────────────────────────────────┤ │ Overall Health: 🟡 MODERATE (7.2/10) │ │ Search Method: claudemem v0.3.0 (AST + PageRank) │ │ │ │ Dimensions: │ │ ├── Architecture: 🟢 GOOD (8/10) [map analysis] │ │ ├── Implementation: 🟡 MODERATE (7/10) [callers/callees] │ │ ├── Testing: 🔴 POOR (5/10) [test-gaps] │ │ ├── Reliability: 🟢 GOOD (8/10) [context tracing] │ │ ├── Security: 🟡 MODERATE (7/10) [auth callers] │ │ ├── Performance: 🟢 GOOD (8/10) [async patterns] │ │ └── Code Health: 🟡 MODERATE (6/10) [dead-code + impact] │ │ │ │ Critical: 3 | Major: 7 | Minor: 15 │ │ │ │ Search Feedback: │ │ └── Performance queries: 2 submitted │ │ └── Helpful results: 5 │ │ └── Unhelpful results: 3 │ └─────────────────────────────────────────────────────────────────┘
### Dimension 1: Architecture (from map)
Core Abstractions (PageRank > 0.05): ├── UserService (0.092) - Central business logic ├── Database (0.078) - Data access foundation ├── AuthMiddleware (0.056) - Security boundary └── EventBus (0.051) - Cross-cutting concerns
Layer Structure: ┌─────────────────────────────────────────────────────────┐ │ PRESENTATION (src/controllers/) │ │ └── UserController (0.034) │ │ └── AuthController (0.028) │ │ ↓ │ │ BUSINESS (src/services/) │ │ └── UserService (0.092) ⭐HIGH PAGERANK │ │ └── AuthService (0.067) │ │ ↓ │ │ DATA (src/repositories/) │ │ └── UserRepository (0.045) │ │ └── Database (0.078) ⭐HIGH PAGERANK │ └─────────────────────────────────────────────────────────┘
### Dimension 2: Implementation (from callers/callees)
Critical Data Flows:
processPayment (PageRank: 0.045) ├── CALLEES (dependencies): │ ├── validateCard → stripeClient.validateCard │ ├── getCustomer → Database.query │ ├── chargeStripe → stripeClient.charge │ └── saveTransaction → TransactionRepository.save │ └── CALLERS (usage): ├── CheckoutController.submit:45 ├── SubscriptionService.renew:89 └── RetryQueue.processPayment:23
### Dimension 3: Test Coverage (from callers)
| Function | Test Callers | Prod Callers | Coverage |
|---|---|---|---|
| authenticateUser | 5 | 12 | ✅ Good |
| processPayment | 3 | 8 | ✅ Good |
| calculateDiscount | 0 | 4 | ❌ None |
| sendEmail | 1 | 6 | ⚠️ Low |
| updateUserProfile | 0 | 3 | ❌ None |
🔴 CRITICAL GAPS (high PageRank + 0 test callers): └── calculateDiscount (PageRank: 0.034) └── callers: 4 production, 0 tests
### Dimension 4: Reliability (from context)
Error Handling Chain:
handleAuthError (context analysis): ├── Defined: src/middleware/auth.ts:45 ├── CALLERS (error sources): │ ├── validateToken:23 → throws on invalid │ ├── refreshSession:67 → throws on expired │ └── checkPermission:89 → throws on denied └── CALLEES (error handling): ├── logError → Logger.error ├── notifyAdmin → AlertService.send (if critical) └── formatResponse → ErrorFormatter.toJSON
### Dimension 5: Security (from symbol + callers)
Authentication Flow:
authenticate (PageRank: 0.067) ├── Location: src/services/auth.ts:23-67 ├── CALLEES: │ ├── bcrypt.compare (password verification) │ ├── jwt.sign (token generation) │ └── SessionStore.create (session persistence) └── CALLERS (entry points): ├── LoginController.login:12 ✅ ├── OAuthController.callback:45 ✅ └── APIMiddleware.verify:23 ⚠️ (rate limiting?)
### Dimension 6: Performance (from map + callees)
Database Access Patterns:
UserRepository.findWithRelations (PageRank: 0.028) ├── CALLEES: │ ├── Database.query (1 call) │ ├── RelationLoader.load (per relation) ⚠️ N+1? │ └── Cache.get (optimization) └── CALLERS: 8 locations └── 3 in loops ⚠️ Potential N+1
Recommendation: Batch relation loading or use joins
---
## Action Items (Prioritized by PageRank Impact)
🔴 IMMEDIATE (This Sprint) - Affects High-PageRank Code
-
Add tests for calculateDiscount (PageRank: 0.034) └── callers show: 4 production uses, 0 tests
-
Fix N+1 query in UserRepository.findWithRelations └── callees show: RelationLoader called per item
-
Add rate limiting to APIMiddleware.verify └── callers show: All API endpoints exposed
🟠 SHORT-TERM (Next 2 Sprints)
-
Add error recovery to PaymentService └── context shows: No retry on Stripe failures
-
Increase test coverage for AuthService └── callers show: Only 2 test files cover critical code
🟡 MEDIUM-TERM (This Quarter)
-
Refactor UserService (PageRank: 0.092) └── callees show: 23 dependencies (god class pattern)
-
Add observability to EventBus └── callers show: 15 publishers, no monitoring
---
## Result Validation Pattern
After EVERY claudemem command, validate results to ensure quality:
### Validation Per Dimension
Each dimension MUST validate its claudemem results before proceeding:
**Dimension 1: Architecture (map)**
```bash
RESULTS=$(claudemem --agent map)
EXIT_CODE=$?
# Check for command failure
if [ "$EXIT_CODE" -ne 0 ]; then
echo "ERROR: claudemem map failed"
# Diagnose and ask user (see Fallback Protocol below)
exit 1
fi
# Check for empty results
if [ -z "$RESULTS" ]; then
echo "WARNING: No architectural symbols found - index may be empty"
# Ask user to reindex or cancel
fi
# Validate PageRank values present
if ! echo "$RESULTS" | grep -q "pagerank:"; then
echo "WARNING: No PageRank data - index may be corrupted or outdated"
# Ask user to reindex
fi
Dimension 2-6: All Other Commands
RESULTS=$(claudemem --agent [command] [args])
EXIT_CODE=$?
# Check exit code
if [ "$EXIT_CODE" -ne 0 ]; then
# Diagnose index health
DIAGNOSIS=$(claudemem --version && ls -la .claudemem/index.db 2>&1)
# Use AskUserQuestion for recovery options
fi
# Check for empty/irrelevant results
# 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 query - potentially irrelevant
# Use AskUserQuestion (see Fallback Protocol)
fi
Dimension 3: Test Coverage (callers)
RESULTS=$(claudemem --agent callers $FUNCTION)
# Even 0 callers is valid - but validate it's not an error
if echo "$RESULTS" | grep -qi "error\|not found"; then
# Actual error vs no callers
# Use AskUserQuestion
fi
FALLBACK PROTOCOL
CRITICAL: Never use grep/find/Glob without explicit user approval.
╔══════════════════════════════════════════════════════════════════════════════╗
║ ║
║ FALLBACK PROTOCOL (NEVER SILENT) ║
║ ║
║ If claudemem fails OR returns irrelevant results: ║
║ ║
║ 1. STOP - Do not silently switch to grep/find ║
║ 2. DIAGNOSE - Run claudemem status to check index health ║
║ 3. COMMUNICATE - Tell user what happened ║
║ 4. ASK - Get explicit user permission via AskUserQuestion ║
║ ║
║ grep/find/Glob ARE FORBIDDEN without explicit user approval ║
║ ║
╚══════════════════════════════════════════════════════════════════════════════╝
Fallback Decision Tree
If claudemem fails or returns unexpected results:
- STOP - Do not silently switch tools
- DIAGNOSE - Run
claudemem status - REPORT - Tell user what happened
- ASK - Use AskUserQuestion for next steps
// Fallback AskUserQuestion Template
AskUserQuestion({
questions: [{
question: "claudemem [command] failed or returned irrelevant 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 semantic understanding" },
{ label: "Cancel", description: "Stop investigation" }
]
}]
})
Grep Fallback Warning
If user explicitly chooses grep fallback, display this warning:
## WARNING: Using Fallback Search (grep)
You have chosen to use grep as a fallback. Please understand the limitations:
| Feature | claudemem | grep |
|---------|-----------|------|
| Semantic understanding | Yes | No |
| Call graph analysis | Yes | No |
| Symbol relationships | Yes | No |
| PageRank ranking | Yes | No |
| False positives | Low | High |
**Recommendation:** After completing this task, run `claudemem index` to rebuild
the index for future investigations.
Proceeding with grep...
🚫 FORBIDDEN: DO NOT USE
# ❌ ALL OF THESE ARE FORBIDDEN
grep -r "pattern" .
rg "pattern"
find . -name "*.ts"
git grep "term"
Glob({ pattern: "**/*.ts" })
Grep({ pattern: "function" })
✅ REQUIRED: ALWAYS USE
# ✅ claudemem v0.3.0 AST Commands
claudemem --agent map "query" # Architecture
claudemem --agent symbol <name> # Location
claudemem --agent callers <name> # Impact
claudemem --agent callees <name> # Dependencies
claudemem --agent context <name> # Full chain
claudemem --agent search "query" # Semantic
CRITICAL: NEVER TRUNCATE CLAUDEMEM OUTPUT
╔══════════════════════════════════════════════════════════════════════════════╗
║ ║
║ ⛔ OUTPUT TRUNCATION IS FORBIDDEN ║
║ ║
║ claudemem output is ALREADY OPTIMIZED for LLM context windows. ║
║ Truncating it may hide the most critical results. ║
║ ║
║ ❌ NEVER DO THIS (any form of output truncation): ║
║ claudemem --agent map "query" | head -80 ║
║ claudemem --agent callers UserService | head -100 ║
║ claudemem --agent callees Func | tail -50 ║
║ claudemem --agent impact Svc | head -N ║
║ claudemem --agent search "auth" | grep -m 10 "pattern" ║
║ claudemem --agent map "q" | awk 'NR <= 50' ║
║ claudemem --agent callers X | sed '50q' ║
║ claudemem --agent search "x" | sort | head -20 ║
║ claudemem --agent map "q" | grep "pattern" | head -20 ║
║ ║
║ WHY tail IS EQUALLY PROBLEMATIC: ║
║ tail skips the BEGINNING of output, which often contains: ║
║ • Summary headers showing total counts ║
║ • Highest-ranked results (PageRank, relevance score) ║
║ • Context that explains what follows ║
║ ║
║ ✅ ALWAYS DO THIS: ║
║ claudemem --agent map "query" ║
║ claudemem --agent callers UserService ║
║ claudemem --agent callees Func ║
║ claudemem --agent impact Svc ║
║ claudemem --agent search "auth" -n 10 # Use built-in limit ║
║ ║
║ WHY THIS MATTERS: ║
║ • search results are sorted by relevance - truncating loses best matches ║
║ • map results are sorted by PageRank - truncating loses core architecture ║
║ • callers/callees show ALL dependencies - truncating causes missed changes ║
║ • impact shows full blast radius - truncating underestimates risk ║
║ ║
║ ═══════════════════════════════════════════════════════════════════════ ║
║ IF OUTPUT IS TOO LARGE, USE BUILT-IN FLAGS: ║
║ ═══════════════════════════════════════════════════════════════════════ ║
║ ║
║ --tokens N Token-limited output (respects LLM context) ║
║ Example: claudemem --agent map "query" --tokens 2000 ║
║ ║
║ --page-size N Pagination with N results per page ║
║ --page N Fetch specific page number ║
║ Example: claudemem --agent search "x" --page-size 20 --page 1║
║ ║
║ -n N Limit result count at query level (not post-hoc) ║
║ Example: claudemem --agent search "auth" -n 10 ║
║ ║
║ --max-depth N Limit traversal depth (for context, callers, impact) ║
║ Example: claudemem --agent context Func --max-depth 3 ║
║ ║
║ ACCEPTABLE: Piping to file for later analysis ║
║ claudemem --agent map "query" > /tmp/full-map.txt ║
║ (Full output preserved, can be processed separately) ║
║ ║
╚══════════════════════════════════════════════════════════════════════════════╝
NOTE: The freshness check pattern head -5 for sampling stale files remains valid.
This prohibition applies only to truncating claudemem COMMAND OUTPUT.
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+)
Cross-Plugin Integration
This skill should be used by ANY agent that needs deep analysis:
| Agent Type | Should Use | From Plugin |
|---|---|---|
frontend-architect | ultrathink-detective | frontend |
api-architect | ultrathink-detective | bun |
senior-code-reviewer | ultrathink-detective | frontend |
| Any architect agent | ultrathink-detective | any |
Agents reference this skill in their frontmatter:
---
skills: code-analysis:ultrathink-detective
---
⚠️ FINAL REMINDER
╔══════════════════════════════════════════════════════════════════════════════╗
║ ║
║ ULTRATHINK = ALL claudemem v0.3.0 AST COMMANDS ║
║ ║
║ WORKFLOW: ║
║ 1. claudemem --agent map ← Architecture (PageRank) ║
║ 2. claudemem --agent symbol <name> ← Exact locations ║
║ 3. claudemem --agent callers <name> ← Impact analysis ║
║ 4. claudemem --agent callees <name> ← Dependencies ║
║ 5. claudemem --agent context <name> ← Full call chain ║
║ 6. claudemem --agent search <query> ← Semantic search ║
║ 7. Read specific file:line (NOT whole files) ║
║ 8. claudemem feedback ... ← Report helpful/unhelpful (if search used) ║
║ ║
║ ❌ grep, find, rg, Glob, Grep tool ║
║ ║
║ PageRank > 0.05 = Architectural pillar = Analyze FIRST ║
║ High PageRank + 0 test callers = CRITICAL coverage gap ║
║ Performance dimension uses search → Track feedback for Dimension 6 ║
║ ║
╚══════════════════════════════════════════════════════════════════════════════╝
Maintained by: MadAppGang Plugin: code-analysis v2.7.0 Last Updated: December 2025 (v3.4.0 - Search feedback protocol support)
Repository
