Marketplace

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.

allowed_tools: Bash, Task, Read, AskUserQuestion

model: opus

$ Installer

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

SKILL.md

View on GitHub →

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)