howto-functional-vs-imperative_skill

Overview

This skill enforces the Functional Core / Imperative Shell (FCIS) pattern when writing or refactoring Python code. It mandates separating pure business logic (Functional Core) from side effects and orchestration (Imperative Shell) and requires a file-level classification comment for every application source file. The goal is easier testing, clearer boundaries, and fewer architecture-driven bugs.

How this skill works

When applied, the skill inspects code and guides decisions: put deterministic computations, validations, and transformations into Functional Core files and keep file I/O, database access, HTTP calls, environment reads, and orchestration in Imperative Shell files. Every new or modified application file must include a pattern comment: Functional Core, Imperative Shell, or Mixed (needs refactoring) with justification for unavoidable mixing. The workflow enforces gather -> process -> persist for every operation.

When to use it

• Creating any new code file or module
• Refactoring functions that mix I/O and business logic
• During code reviews to check architectural boundaries
• When tests require heavy mocking or integration setup
• Before adding DB, file, or network calls to logic code

Best practices

• Always add a // pattern: ... comment to application source files you create or change
• Extract pure computations into Core functions that accept data, not connections
• Make shells thin: gather external inputs, call Core, then persist results
• Pass timestamps, random seeds, and other non-deterministic values from the Shell
• Use loggers as the only permitted side effect in Core; pass no-op loggers in tests
• If mixing is unavoidable, document precise technical justification in a Mixed file comment

Example use cases

• Refactor a function that reads a config file and applies business rules: move parsing to Shell, rules to Core
• Write unit tests for complex calculations without mocking DB or HTTP
• Create a CLI command that gathers input, calls Core processors, then writes outputs
• Convert a monolithic order-processing module into a Shell that calls Core calculation functions
• Review PRs for accidental I/O inside validation or transformation functions