architect-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 IS THE PRIMARY COMMAND             ║
║   ✅ claudemem --nologo symbol <name> --raw FOR EXACT LOCATIONS              ║
║                                                                              ║
║   ⭐ v0.3.0: PageRank shows which symbols are architectural pillars         ║
║                                                                              ║
╚══════════════════════════════════════════════════════════════════════════════╝
```

# Architect Detective Skill

**Version:** 3.3.0
**Role:** Software Architect
**Purpose:** Deep architectural investigation using AST structural analysis with PageRank and dead-code detection

## Role Context

You are investigating this codebase as a **Software Architect**. Your focus is on:
- **System boundaries** - Where modules, services, and layers begin and end
- **Design patterns** - Architectural patterns used (MVC, Clean Architecture, DDD, etc.)
- **Dependency flow** - How components depend on each other
- **Abstraction layers** - Interfaces, contracts, and abstractions
- **Core abstractions** - High-PageRank symbols that everything depends on

## Why `map` is Perfect for Architecture

The `map` command with PageRank shows you:
- **High-PageRank symbols** = Core abstractions everything depends on
- **Symbol kinds** = classes, interfaces, functions organized by type
- **File distribution** = Where architectural layers live
- **Dependency centrality** = Which code is most connected

## Architect-Focused Commands (v0.3.0)

### Architecture Discovery (use `map`)

```bash
# Get high-level architecture overview
claudemem --nologo map "architecture layers" --raw

# Find core abstractions (highest PageRank)
claudemem --nologo map --raw  # Full map, sorted by importance

# Map specific architectural concerns
claudemem --nologo map "service layer business logic" --raw
claudemem --nologo map "repository data access" --raw
claudemem --nologo map "controller API endpoints" --raw
claudemem --nologo map "middleware request handling" --raw
```

### Layer Boundary Discovery

```bash
# Find interfaces/contracts (architectural boundaries)
claudemem --nologo map "interface contract abstract" --raw

# Find dependency injection points
claudemem --nologo map "inject provider module" --raw

# Find configuration/bootstrap
claudemem --nologo map "config bootstrap initialize" --raw
```

### Pattern Discovery

```bash
# Find factory patterns
claudemem --nologo map "factory create builder" --raw

# Find repository patterns
claudemem --nologo map "repository persist query" --raw

# Find event-driven patterns
claudemem --nologo map "event emit subscribe handler" --raw
```

### Dependency Analysis

```bash
# For a core abstraction, see what depends on it
claudemem --nologo callers CoreService --raw

# See what the abstraction depends on
claudemem --nologo callees CoreService --raw

# Get full dependency context
claudemem --nologo context CoreService --raw
```

### Dead Code Detection (v0.4.0+ Required)

```bash
# Find unused symbols for cleanup
claudemem --nologo dead-code --raw

# Only truly dead code (very low PageRank)
claudemem --nologo dead-code --max-pagerank 0.005 --raw
```

**Architectural insight**: Dead code indicates:
- Failed features that were never removed
- Over-engineering (abstractions nobody uses)
- Potential tech debt cleanup opportunities

High PageRank + dead = Something broke recently (investigate!)
Low PageRank + dead = Safe to remove

**Handling Results:**
```bash
DEAD_CODE=$(claudemem --nologo dead-code --raw)
if [ -z "$DEAD_CODE" ]; then
  echo "No dead code found - architecture is well-maintained"
else
  # Categorize by risk
  HIGH_PAGERANK=$(echo "$DEAD_CODE" | awk '$5 > 0.01')
  LOW_PAGERANK=$(echo "$DEAD_CODE" | awk '$5 <= 0.01')

  if [ -n "$HIGH_PAGERANK" ]; then
    echo "WARNING: High-PageRank dead code found (possible broken references)"
    echo "$HIGH_PAGERANK"
  fi

  if [ -n "$LOW_PAGERANK" ]; then
    echo "Cleanup candidates (low PageRank):"
    echo "$LOW_PAGERANK"
  fi
fi
```

**Limitations Note:**
Results labeled "Potentially Dead" require manual verification for:
- Dynamically imported modules
- Reflection-accessed code
- External API consumers

## PHASE 0: MANDATORY SETUP

### Step 1: Verify claudemem v0.3.0

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

### Step 2: If Not Installed → STOP

Use AskUserQuestion (see ultrathink-detective for template)

### 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 (see template in ultrathink-detective)
fi
```

### Step 4: Index if Needed

```bash
claudemem index
```

---

## Workflow: Architecture Analysis (v0.3.0)

### Phase 1: Map the Landscape

```bash
# Get structural overview with PageRank
claudemem --nologo map --raw

# Focus on high-PageRank symbols (> 0.01) - these are architectural pillars
```

### Phase 2: Identify Layers

```bash
# Map each layer
claudemem --nologo map "controller handler endpoint" --raw  # Presentation
claudemem --nologo map "service business logic" --raw       # Business
claudemem --nologo map "repository database query" --raw    # Data
```

### Phase 3: Trace Dependencies

```bash
# For each high-PageRank symbol, understand its role
claudemem --nologo symbol UserService --raw
claudemem --nologo callers UserService --raw  # Who depends on it?
claudemem --nologo callees UserService --raw  # What does it depend on?
```

### Phase 4: Identify Boundaries

```bash
# Find interfaces (architectural contracts)
claudemem --nologo map "interface abstract" --raw

# Check how implementations connect
claudemem --nologo callers IUserRepository --raw
```

### Phase 5: Cleanup Opportunities (v0.4.0+ Required)

```bash
# Find dead code
DEAD_CODE=$(claudemem --nologo dead-code --raw)

if [ -z "$DEAD_CODE" ]; then
  echo "No cleanup needed - codebase is well-maintained"
else
  # For each dead symbol:
  # - Check PageRank (low = utility,