---
title: Dead Code Detection - Quick Start Guide
description: Quick reference for running dead code detection
category: quality-standards
created: 2026-01-23
status: active
---

# Dead Code Detection - Quick Start Guide

Quick reference for identifying and cleaning up dead code in Kollabor CLI.

## Quick Commands

### Run Basic Scan

```bash
# Text report to console
python scripts/detect_dead_code.py

# Save to file
python scripts/detect_dead_code.py -o reports/dead_code_report.txt
```

### Generate Reports

```bash
# Markdown report
python scripts/detect_dead_code.py --format markdown > reports/dead_code.md

# JSON report (for automation)
python scripts/detect_dead_code.py --format json -o reports/dead_code.json
```

### Filter Results

```bash
# Only backup files
python scripts/detect_dead_code.py --category backup

# Only high confidence findings
python scripts/detect_dead_code.py --confidence high

# Confirmed dead code only
python scripts/detect_dead_code.py --category confirmed_dead --confidence high
```

## Common Workflows

### Weekly Cleanup

```bash
# 1. Run scan
python scripts/detect_dead_code.py --format markdown > reports/dead_code_$(date +%Y%m%d).md

# 2. Review backup files
python scripts/detect_dead_code.py --category backup

# 3. Remove backup files
find . -name "*.bak" -delete
find . -name "*.backup" -delete
find . -name "*.old" -delete
```

### Pre-Release Check

```bash
# 1. Full scan with high confidence
python scripts/detect_dead_code.py --confidence high -o reports/pre_release_check.txt

# 2. Check for TODOs
python scripts/detect_dead_code.py --category placeholder

# 3. Review findings
cat reports/pre_release_check.txt
```

### Monthly Deep Dive

```bash
# 1. Generate comprehensive JSON report
python scripts/detect_dead_code.py --format json -o reports/monthly_$(date +%Y%m).json

# 2. Create markdown for review
python scripts/detect_dead_code.py --format markdown -o reports/monthly_$(date +%Y%m).md

# 3. Track metrics over time
# Compare with previous month's JSON report
```

## Understanding Categories

### backup
Backup and duplicate files (.bak, .backup, .old)
**Action:** Delete immediately

### confirmed_dead
Unused code with high confidence
**Action:** Review and likely delete

### disconnected
Implemented but not connected to main codebase
**Action:** Document and keep for future integration

### placeholder
Intentional stubs (TODO, pass, NotImplementedError)
**Action:** Keep, ensure proper documentation

### dynamic
Code called dynamically at runtime
**Action:** Keep, no changes needed

## Confidence Levels

### high (90-100%)
Very likely unused, safe to remove after quick review

### medium (60-89%)
Probably unused, requires manual verification

### low (30-59%)
Uncertain, detailed investigation required

## Quick Cleanup Checklist

Before starting:
- [ ] Ensure working directory is clean (git status)
- [ ] Create new branch: `git checkout -b cleanup/dead-code-$(date +%Y%m%d)`

Cleanup steps:
- [ ] Run scan: `python scripts/detect_dead_code.py`
- [ ] Delete backup files
- [ ] Review high-confidence findings
- [ ] Remove confirmed dead code
- [ ] Run tests: `python tests/run_tests.py`
- [ ] Commit changes
- [ ] Create PR

## Advanced Usage

### With Vulture (Recommended)

Install vulture for enhanced detection:
```bash
pip install vulture

# Vulture will automatically run during scan
python scripts/detect_dead_code.py
```

### Custom Ignore Patterns

Edit the script to add ignore patterns:
```python
# In scripts/detect_dead_code.py
self.ignore_patterns = [
    "__pycache__",
    ".git",
    "your_custom_pattern",
]
```

### Whitelist Dynamic Code

Add patterns to `.vulture-whitelist.py`:
```python
# Dynamic command handler
def cmd_mycommand():
    pass
```

## Troubleshooting

### False Positives

If vulture reports code as unused but it's actually called:

1. **Check if it's dynamic:** Look for getattr, decorators, plugin system
2. **Add to whitelist:** Edit `.vulture-whitelist.py`
3. **Document:** Add comment explaining dynamic usage

### High False Positive Rate

Adjust confidence threshold:
```bash
# Only very high confidence
python scripts/detect_dead_code.py --confidence high
```

## Integration with CI/CD

### GitHub Actions

```yaml
name: Dead Code Check
on: [pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Install dependencies
        run: pip install vulture
      - name: Run dead code detection
        run: python scripts/detect_dead_code.py --confidence high
```

### Pre-Commit Hook

```bash
# .git/hooks/pre-commit
#!/bin/bash

# Check for backup files
if git diff --cached --name-only | grep -E '\.(bak|backup|old)$'; then
    echo "Error: Attempting to commit backup files"
    exit 1
fi
```

## Best Practices

1. **Run regularly:** Weekly scans catch issues early
2. **Review manually:** Don't blindly delete everything
3. **Test after cleanup:** Always run tests after removing code
4. **Document decisions:** Keep notes on why code was kept/removed
5. **Track metrics:** Monitor code health over time

## Getting Help

- **Full Documentation:** See `docs/standards/quality/dead-code-detection-methodology.md`
- **Report Issues:** If detection script has bugs, create GitHub issue
- **Questions:** Ask in team chat or code review

## Quick Reference Table

| Task | Command |
|------|---------|
| Basic scan | `python scripts/detect_dead_code.py` |
| Markdown report | `python scripts/detect_dead_code.py -f markdown > report.md` |
| JSON report | `python scripts/detect_dead_code.py -f json -o report.json` |
| Backup files only | `python scripts/detect_dead_code.py -c backup` |
| High confidence | `python scripts/detect_dead_code.py --confidence high` |
| Delete backups | `find . -name "*.bak" -delete` |
| Install vulture | `pip install vulture` |

## Next Steps

After your first scan:

1. Review the methodology: `docs/standards/quality/dead-code-detection-methodology.md`
2. Set up automated weekly scans
3. Add pre-commit hooks to prevent backup file commits
4. Schedule quarterly deep reviews
5. Track code health metrics over time

---

For comprehensive documentation and advanced usage, see:
- `docs/standards/quality/dead-code-detection-methodology.md`
- `.vulture-whitelist.py` - Dynamic code patterns
- `scripts/detect_dead_code.py` - Detection script source
