ultrathink-detective

What this skill does

# 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 (