---
name: ultrathink-detective
description: "⚡ Comprehensive analysis skill. Best for: 'comprehensive audit', 'deep analysis', 'full codebase review', 'multi-perspective investigation', 'complex questions'. Combines all perspectives (architect+developer+tester+debugger). Uses Opus model with full claudemem AST analysis."
allowed-tools: Bash, Task, Read, AskUserQuestion
model: opus
---

# Ultrathink Detective Skill

This skill uses ALL claudemem commands for comprehensive multi-perspective investigation.

## Combines All Detective Perspectives

| Perspective | Focus | Commands Used |
|-------------|-------|---------------|
| Architect | System design, layers | `map`, `symbol` |
| Developer | Implementation, flow | `callers`, `callees` |
| Tester | Coverage, gaps | `callers` for tests |
| Debugger | Root cause, chains | `context` |

**Full command set:**
- `claudemem --agent map "query"` - Architecture overview
- `claudemem --agent symbol <name>` - Exact locations
- `claudemem --agent callers <name>` - Impact analysis
- `claudemem --agent callees <name>` - Dependency tracing
- `claudemem --agent context <name>` - Full call chain
- `claudemem --agent search "query"` - Semantic search

# 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

```bash
which claudemem && claudemem --version
# Must be 0.3.0+
```

### Step 2: If Not Installed → STOP

**DO NOT FALL BACK TO GREP.** Use AskUserQuestion:

```typescript
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

```bash
# 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:

```bash
# 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:**

```typescript
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

```bash
claudemem index
```

---

## Multi-Dimensional Analysis Framework (v0.3.0)

### Dimension 1: Architecture (map command)

```bash
# 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)

```bash
# 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)

```bash
# 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)

```bash
# 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)

```bash
# 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

   1. Add tests for calculateDiscount (PageRank: 0.034)
      └── callers show: 4 production uses, 0 tests

   2. Fix N+1 query in UserRepository.findWithRelations
      └── callees show: RelationLoader called per item

   3. Add rate limiting to APIMiddleware.verify
      └── callers show: All API endpoints exposed

🟠 SHORT-TERM (Next 2 Sprints)

   4. Add error recovery to PaymentService
      └── context shows: No retry on Stripe failures

   5. Increase test coverage for AuthService
      └── callers show: Only 2 test files cover critical code

🟡 MEDIUM-TERM (This Quarter)

   6. Refactor UserService (PageRank: 0.092)
      └── callees show: 23 dependencies (god class pattern)

   7. 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**

```bash
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)**

```bash
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:

1. **STOP** - Do not silently switch tools
2. **DIAGNOSE** - Run `claudemem status`
3. **REPORT** - Tell user what happened
4. **ASK** - Use AskUserQuestion for next steps

```typescript
// 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:

```markdown
## 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

```bash
# ❌ 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

```bash
# ✅ 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

```bash
# 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:**
```yaml
---
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)