ultrathink-detective

What this skill does

# ⛔⛔⛔ 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 --nologo map "query" --raw FOR ARCHITECTURE                   ║
║   ✅ claudemem --nologo symbol <name> --raw FOR EXACT LOCATIONS              ║
║   ✅ claudemem --nologo callers <name> --raw FOR IMPACT ANALYSIS             ║
║   ✅ claudemem --nologo callees <name> --raw FOR DEPENDENCY TRACING          ║
║   ✅ claudemem --nologo context <name> --raw FOR FULL CALL CHAIN             ║
║   ✅ claudemem --nologo search "query" --raw 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

```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 --nologo map --raw

# Focus on high-PageRank symbols (> 0.05) - these ARE the architecture

# Layer identification
claudemem --nologo map "controller handler endpoint" --raw   # Presentation
claudemem --nologo map "service business logic" --raw        # Business
claudemem --nologo map "repository database query" --raw     # Data

# Pattern detection
claudemem --nologo map "factory create builder" --raw
claudemem --nologo map "interface abstract contract" --raw
claudemem --nologo map "event emit subscribe" --raw
```

### Dimension 2: Implementation (callers/callees)

```bash
# For high-PageRank symbols, trace dependencies
claudemem --nologo callees PaymentService --raw

# What calls critical code?
claudemem --nologo callers processPayment --raw

# Full dependency chain
claudemem --nologo context OrderController --raw
```

### Dimension 3: Test Coverage (callers analysis)

```bash
# Find tests for critical functions
claudemem --nologo callers authenticateUser --raw
# Look for callers from *.test.ts or *.spec.ts

# Map test infrastructure
claudemem --nologo map "test spec describe it" --raw
claudemem --nologo map "mock stub spy helper" --raw

# Coverage gaps =