python-best-practices-fail-fast-imports

What this skill does

# Validate Fail-Fast Imports

## Purpose

Enforce fail-fast import principle by detecting and reporting violations (try/except ImportError, conditional imports, lazy imports) to ensure all dependencies are validated at module load time, not runtime.

## Table of Contents

### Core Sections
- [Purpose](#purpose) - Enforce fail-fast imports to catch missing dependencies early
- [When to Use This Skill](#when-to-use-this-skill) - Trigger conditions for skill invocation
- [What This Skill Does](#what-this-skill-does) - Detection capabilities and rules
- [Quick Start](#quick-start) - Fastest way to validate imports
- [Violation Patterns Detected](#violation-patterns-detected) - 4 anti-patterns with fixes
  - [Pattern 1: try/except ImportError](#pattern-1-tryexcept-importerror) - Optional import detection
  - [Pattern 2: Conditional Imports](#pattern-2-conditional-imports) - Config-based imports
  - [Pattern 3: Lazy Imports](#pattern-3-lazy-imports) - Function-level imports
  - [Pattern 4: Import with Default Fallback](#pattern-4-import-with-default-fallback) - Silent degradation
- [Validation Process](#validation-process) - 5-step validation workflow
- [Detection Patterns](#detection-patterns) - Grep patterns for automation
- [Usage Examples](#usage-examples) - Pre-commit, manual, fix guidance
  - [Example 1: Pre-Commit Validation](#example-1-pre-commit-validation)
  - [Example 2: Manual Check](#example-2-manual-check)
  - [Example 3: Fix Guidance](#example-3-fix-guidance)
- [Expected Outcomes](#expected-outcomes) - Success/failure output formats
- [Integration Points](#integration-points) - Hook, quality gate, agent integration

### Supporting Resources
- [references/reference.md](references/reference.md) - Complete anti-pattern reference and fix procedures
- CLAUDE.md - Project fail-fast principles (in project using this skill)

## When to Use This Skill

Use this skill when:
- User modifies import statements
- Before committing changes
- As part of quality gates (pre-commit hooks)
- User asks about import patterns
- Reviewing code for fail-fast compliance

## What This Skill Does

Detects and reports violations of the fail-fast import principle:

### Fail-Fast Import Rules

1. **All imports at top level:** No imports inside functions/classes
2. **No optional imports:** No try/except ImportError patterns
3. **No conditional imports:** No if/else import logic
4. **No lazy imports:** All dependencies imported immediately

### Why Fail-Fast Imports?

**Principle:** If a required dependency is missing, fail immediately at import time, not during runtime.

**Benefits:**
- Catch missing dependencies during startup
- Clear error messages (ImportError vs AttributeError later)
- Easier debugging (fail at source, not downstream)
- Testable dependencies (mocking works correctly)

## Quick Start

**User:** "Check if my imports are fail-fast compliant"

**What happens:**
1. Skill scans Python files for import anti-patterns
2. Reports violations with file:line references
3. Provides specific fixes for each violation

**Result:** ✅ Pass (no violations) or ❌ Fail (violations with fixes)

**Example output:**
```
✅ Validation: PASSED - 145 files checked, 0 violations
```
or
```
❌ Violation at src/utils/helper.py:10
   Pattern: try/except ImportError
   Fix: Make dependency required, remove try/except
```

## Violation Patterns Detected

### Pattern 1: try/except ImportError

```python
# ❌ VIOLATION
try:
    import tree_sitter
    TREE_SITTER_AVAILABLE = True
except ImportError:
    TREE_SITTER_AVAILABLE = False
```

**Why this is bad:**
- Hides missing dependency until runtime
- Creates optional behavior (inconsistent)
- Hard to test both code paths

**Fix:**
```python
# ✅ CORRECT
import tree_sitter  # Fail fast if missing
# If tree_sitter is truly optional, remove feature or make required
```

### Pattern 2: Conditional Imports

```python
# ❌ VIOLATION
if USE_NEO4J:
    from neo4j import AsyncGraphDatabase
else:
    AsyncGraphDatabase = None
```

**Why this is bad:**
- Runtime behavior depends on config
- Can't validate dependencies at startup

**Fix:**
```python
# ✅ CORRECT
from neo4j import AsyncGraphDatabase  # Always import
# Configuration controls usage, not imports
```

### Pattern 3: Lazy Imports

```python
# ❌ VIOLATION
def search_code(query: str):
    from application.services import SearchService  # Inside function
    service = SearchService()
    ...
```

**Why this is bad:**
- ImportError could happen mid-execution
- Harder to track dependencies
- Slower (import on every call)

**Fix:**
```python
# ✅ CORRECT
from application.services import SearchService  # Top level

def search_code(query: str):
    service = SearchService()
    ...
```

### Pattern 4: Import with Default Fallback

```python
# ❌ VIOLATION
try:
    from fast_library import fast_function
except ImportError:
    from slow_library import slow_function as fast_function
```

**Why this is bad:**
- Silent performance degradation
- User doesn't know which library is used
- Hard to reproduce issues

**Fix:**
```python
# ✅ CORRECT
from fast_library import fast_function  # Fail if not available
# Document in requirements.txt, fail at install time
```

## Validation Process

1. **Scan Python files** for import-related patterns
2. **Detect violations** using Grep for common anti-patterns
3. **Report violations** with file:line:column references
4. **Suggest fixes** with concrete examples
5. **Exit code 1** if violations found (blocks commit)

## Detection Patterns

Use Grep to detect these patterns in Python files:

```bash
# Pattern 1: try/except ImportError
grep -rn "except ImportError:" src/

# Pattern 2: Conditional imports
grep -rn "if.*import" src/

# Pattern 3: Lazy imports (imports inside functions)
# This requires context - look for indented imports after def

# Pattern 4: Optional import flags
grep -rn "_AVAILABLE = False" src/
```

## Advanced Topics

For detailed technical documentation, see:
- Anti-pattern detection patterns and regex
- Complete fix procedures for each violation type
- Circular import resolution strategies
- Testing implications and best practices
- Performance analysis and benchmarks

Reference: [reference.md](./reference.md)

## Usage Examples

### Example 1: Pre-Commit Validation

```
User commits changes

Pre-commit hook invokes skill:
validate_fail_fast_imports(changed_files)

Skill returns:
❌ Fail-Fast Import Violations Found

1. try/except ImportError
   File: src/utils/optional_feature.py:15
   Code: try: import tree_sitter ...
   Fix: Make tree_sitter required in requirements.txt, remove try/except

Exit code: 1 (commit blocked)
```

### Example 2: Manual Check

```
User: "Check if my imports follow fail-fast"

Claude invokes skill:
validate_fail_fast_imports("src/")

Returns:
✅ Fail-Fast Import Validation: PASSED

Files checked: 123
Violations: 0

All imports follow fail-fast principle.
```

### Example 3: Fix Guidance

```
User: "How do I fix this ImportError pattern?"

Claude invokes skill:
validate_fail_fast_imports("src/my_module.py")

Returns:
❌ Violation at src/my_module.py:10

Current code:
try:
    import optional_lib
except ImportError:
    optional_lib = None

Recommended fix:
1. If optional_lib is truly required:
   - Add to requirements.txt
   - Remove try/except
   - Import at top: import optional_lib

2. If optional_lib is truly optional:
   - Remove feature that uses it, or
   - Split into separate module (plugin pattern), or
   - Make it required (preferred)

Project policy: Make dependencies explicit and required.
```

## Expected Outcomes

### Success (No Violations)

```
✅ Fail-Fast Import Validation: PASSED

Files checked: 145
Violations: 0

All imports at top level, no optional patterns detected.
```

### Failure (Violations Found)

```
❌ Fail-Fast Import Validation: FAILED

Violations found: 3

1. try/except ImportError
   File: src/services/optional.py:12
   Pattern: try: import X except ImportError: ...
   Impact: HIGH - hides missing d