quality-detect-orphaned-code

What this skill does

# Detect Orphaned Code

## Quick Start

Run orphan detection before marking any feature complete:

```bash
# Quick check for a specific module
grep -r "from.*your_module import\|import.*your_module" src/ --include="*.py" | grep -v test

# If output is EMPTY → Module is orphaned (not imported in production)

# Comprehensive orphan detection (if script exists)
./scripts/verify_integration.sh

# Check specific function usage
grep -r "your_function_name" src/ --include="*.py" | grep -v test | grep -v "^[^:]*:.*def "

# If output is EMPTY → Function is orphaned (never called)
```

## Table of Contents

1. When to Use This Skill
2. What This Skill Does
3. Types of Orphaned Code
4. Detection Methods
5. Step-by-Step Detection Process
6. Automated Detection Scripts
7. Integration with Quality Gates
8. Supporting Files
9. Expected Outcomes
10. Requirements
11. Red Flags to Avoid

## When to Use This Skill

### Explicit Triggers
- "Detect orphaned code"
- "Find dead code in the project"
- "Check for unused modules"
- "Verify no orphaned files exist"
- "Find code that's never imported"
- "Check for integration gaps"

### Implicit Triggers (PROACTIVE)
- **Before marking any feature complete**
- **Before moving ADR from in_progress to completed**
- **After creating new Python modules**
- **After major refactoring**
- **As part of pre-commit quality gates**
- **During code review**

### Debugging Triggers
- "Tests pass but feature doesn't work" (often orphaned code)
- "File exists but nothing happens when I run it"
- "Why isn't my new module being used?"
- "Code review found unused imports"

## What This Skill Does

This skill **detects code that exists but is never used**, preventing the ADR-013 failure mode:

**What it detects:**
1. **Orphaned modules** - Python files never imported in production code
2. **Orphaned functions** - Functions defined but never called
3. **Orphaned classes** - Classes defined but never instantiated
4. **Orphaned nodes** - LangGraph nodes never added to graph
5. **Dead code paths** - Code wired but conditionals never trigger

**What it prevents:**
- Marking incomplete features as "done"
- Moving ADRs to completed when code isn't integrated
- Accumulating technical debt (unused code)
- Confusion for future developers (why does this exist?)

**Why existing tools miss this:**
- **vulture** - Can be fooled by unit tests that import modules
- **mypy** - Only checks types, not usage
- **pytest** - Can pass 100% coverage on orphaned modules
- **ruff** - Checks style, not integration

**This skill complements those tools** by checking integration explicitly.

## Types of Orphaned Code

### Type 1: Orphaned Module (File Never Imported)

**Symptom:** Python file exists, has tests, but is never imported in production code

**Example:**
```python
# File: src/myapp/features/new_feature.py (175 lines)
def process_data(data: dict) -> Result:
    """Process data and return result."""
    # ... implementation ...
```

**Detection:**
```bash
$ grep -r "from.*new_feature import\|import.*new_feature" src/ --include="*.py" | grep -v test
(empty) ❌
```

**Root cause:** File created but never imported in integration point

**Fix:** Import in the consuming module

### Type 2: Orphaned Function (Defined But Never Called)

**Symptom:** Function exists in imported module but is never called

**Example:**
```python
# File: src/myapp/services/utils.py
def helper_function(x: int) -> int:  # Orphaned
    return x * 2

def another_function(x: int) -> int:  # Used
    return x + 1
```

**Detection:**
```bash
$ grep -r "helper_function" src/ --include="*.py" | grep -v test | grep -v "def helper_function"
(empty) ❌  # Only definition, no call-sites

$ grep -r "another_function" src/ --include="*.py" | grep -v test | grep -v "def another_function"
src/myapp/main.py:45:    result = another_function(5)  ✅  # Has call-site
```

**Root cause:** Function created but never invoked

**Fix:** Call the function where needed, or remove it

### Type 3: Orphaned Class (Defined But Never Instantiated)

**Symptom:** Class exists but is never instantiated or subclassed

**Example:**
```python
# File: src/myapp/models/new_model.py
class NewModel:
    def __init__(self, data: dict) -> None:
        self.data = data
```

**Detection:**
```bash
$ grep -r "NewModel" src/ --include="*.py" | grep -v test | grep -v "class NewModel"
(empty) ❌  # Only definition, no instantiation
```

**Root cause:** Class created but never used

**Fix:** Instantiate where needed, or remove

### Type 4: Orphaned LangGraph Node (Node File Exists But Not in Graph)

**Symptom:** Node factory function exists but is never added to graph

**Example:**
```python
# File: src/myapp/graph/architecture_nodes.py
async def create_architecture_review_node(agent):
    """Create architecture review node."""
    # ... implementation ...
```

**Detection:**
```bash
$ grep "architecture_nodes" src/myapp/graph/builder.py
(empty) ❌  # Not imported in builder

$ grep "add_node.*architecture_review" src/myapp/graph/builder.py
(empty) ❌  # Not added to graph
```

**Root cause:** Node created but never wired into graph

**Fix:** Import and add to graph in builder.py

### Type 5: Dead Code Path (Code Wired But Conditional Never Triggers)

**Symptom:** Code is integrated but the path to reach it never executes

**Example:**
```python
# In builder.py
if settings.enable_experimental_features:  # Never True in production
    graph.add_node("experimental", experimental_node)
```

**Detection:**
```bash
# Check configuration
$ grep "enable_experimental_features" .env
# Not set (defaults to False)

# Check logs for execution
$ grep "experimental" logs/*.log
(empty) ❌  # Never executes
```

**Root cause:** Conditional never true in practice

**Fix:** Enable the condition or remove the dead path

## Detection Methods

### Method 1: Manual Grep (Quick Check)

**For a specific module:**
```bash
# Check if module is imported
grep -r "from.*MODULE_NAME import\|import.*MODULE_NAME" src/ --include="*.py" | grep -v test

# Expected: At least one import line from production code
# If empty: Module is orphaned
```

**For a specific function:**
```bash
# Check if function is called
grep -r "FUNCTION_NAME" src/ --include="*.py" | grep -v test | grep -v "def FUNCTION_NAME"

# Expected: At least one call-site
# If empty: Function is orphaned
```

**For a specific class:**
```bash
# Check if class is instantiated
grep -r "CLASS_NAME(" src/ --include="*.py" | grep -v test | grep -v "class CLASS_NAME"

# Expected: At least one instantiation
# If empty: Class is orphaned
```

### Method 2: Comprehensive Script (Automated)

**Script: `scripts/verify_integration.sh`**

```bash
#!/bin/bash
# Detects orphaned modules (created but never imported in production)

set -e

echo "=== Orphan Detection ==="

RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m'

orphaned=0
checked=0

for file in $(find src/ -name "*.py" -type f | sort); do
    module=$(basename "$file" .py)
    dir=$(dirname "$file")

    # Skip special files
    [[ "$module" == "__init__" ]] && continue
    [[ "$module" == "__main__" ]] && continue
    [[ "$module" == "main" ]] && continue
    [[ "$module" == *"test"* ]] && continue

    checked=$((checked + 1))

    # Check if module is imported (excluding self and tests)
    imports=$(grep -r -E "import\s+.*\b${module}\b|from\s+.*\b${module}\b\s+import" src/ \
              --include="*.py" 2>/dev/null | \
              grep -v "$file" | \
              grep -v "test_" | \
              grep -v "__pycache__" | \
              wc -l | tr -d ' ')

    if [ "$imports" -eq 0 ]; then
        # Check if exported via __init__.py
        init_file="$dir/__init__.py"
        init_export=0
        if [ -f "$init_file" ]; then
            init_export=$(grep -c "\b$module\b" "$init_file" 2>/dev/null || echo "0")
        fi

        if [ "$init_export" -eq 0 ]; then
            echo -e "${YELLOW}⚠️  ORPHANED:${NC} $file"
            echo "   No produ