Functional Core Imperative Shell

Functional Core, Imperative Shell (FCIS)

Overview

Core principle: Separate pure business logic (Functional Core) from side effects (Imperative Shell). Pure functions go in one file, I/O operations in another.

Why this matters: Pure functions are trivial to test (no mocks needed). I/O code is isolated to thin shells. Bugs become structurally impossible when business logic has no side effects.

When to Use

Use FCIS when:

• Writing any new code file
• Refactoring existing code
• Reviewing code for architectural decisions
• Deciding where logic belongs

Trigger symptoms:

• "Where should this function go?"
• Creating a new file
• Adding database calls to logic
• Adding file I/O to calculations
• Writing tests that need complex mocking

MANDATORY: File Classification

YOU MUST add pattern comment to every file containing runtime behavior:

// pattern: Functional Core
// pattern: Imperative Shell
// pattern: Mixed (needs refactoring)

If file genuinely cannot be separated (rare), document why: