ultrathink-detective

# 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