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)