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 - Enforce fail-fast imports to catch missing dependencies early
• •When to Use This Skill - Trigger conditions for skill invocation
• •What This Skill Does - Detection capabilities and rules
• •Quick Start - Fastest way to validate imports
• •Violation Patterns Detected - 4 anti-patterns with fixes
  • •Pattern 1: try/except ImportError - Optional import detection
  • •Pattern 2: Conditional Imports - Config-based imports
  • •Pattern 3: Lazy Imports - Function-level imports
  • •Pattern 4: Import with Default Fallback - Silent degradation
• •Validation Process - 5-step validation workflow
• •Detection Patterns - Grep patterns for automation
• •Usage Examples - Pre-commit, manual, fix guidance
  • •Example 1: Pre-Commit Validation
  • •Example 2: Manual Check
  • •Example 3: Fix Guidance
• •Expected Outcomes - Success/failure output formats
• •Integration Points - Hook, quality gate, agent integration

Supporting Resources

• •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

# ❌ 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:

# ✅ CORRECT
import tree_sitter  # Fail fast if missing
# If tree_sitter is truly optional, remove feature or make required

Pattern 2: Conditional Imports

# ❌ 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:

# ✅ CORRECT
from neo4j import AsyncGraphDatabase  # Always import
# Configuration controls usage, not imports

Pattern 3: Lazy Imports

# ❌ 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:

# ✅ CORRECT
from application.services import SearchService  # Top level

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

Pattern 4: Import with Default Fallback

# ❌ 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:

# ✅ 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:

# 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

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 dependency
   Fix: Add to requirements.txt, remove try/except

2. Conditional Import
   File: src/config/loader.py:25
   Pattern: if condition: import X
   Impact: MEDIUM - runtime import failures possible
   Fix: Import at top, use condition at usage site

3. Lazy Import
   File: src/handlers/handler.py:45
   Pattern: import inside function
   Impact: MEDIUM - slower, harder to track deps
   Fix: Move import to top of file

Total violations: 3
Exit code: 1

Integration Points

With Pre-Flight Validation Hook

The pre-flight validation hook in .claude/scripts/pre_flight_validation.py can leverage this skill to validate imports before allowing tool execution.

With Quality Gates

Quality gate scripts in ./scripts/check_all.sh can invoke this skill to ensure fail-fast import compliance as part of the CI/CD process.

With @architecture-guardian

The architecture guardian agent can delegate import validation to this skill rather than implementing validation inline, reducing context load by 96%.

Expected Benefits

Success Metrics

• •Precision: 100% (no false positives)
• •Recall: 95%+ (catches all major patterns)
• •Performance: <0.5s for typical file
• •Invocation Rate: 90%+ of import validations use skill

See Also

• •reference.md - Complete anti-pattern reference, detection patterns, and fix procedures
• •CLAUDE.md - Project fail-fast principles and anti-pattern enforcement (in project using this skill)
• •.claude/scripts/pre_flight_validation.py - Pre-tool-use hook implementation (in project using this skill)