hickey_skill

Overview

This skill teaches how to write functional Python code in the spirit of Rich Hickey: favoring simplicity over mere easiness, immutable values, data-oriented design, and explicit state management. It translates Hickey's principles into practical patterns and idioms you can apply in Python projects. Use it to design systems that are easier to reason about, test, and maintain over time.

How this skill works

The skill inspects code and design choices, recommending data-first alternatives to class-heavy designs and pointing out hidden state and complected responsibilities. It suggests immutable-first patterns, pure functions, single-source-of-truth state containers, and composable transformations. It also provides concrete substitutions (maps/dicts instead of objects, functions instead of methods) and patterns for explicit state handling and validation.

When to use it

• When a codebase suffers from tangled responsibilities or hidden state
• When designing APIs, data models, or integration points that must be stable and testable
• When you need predictable state transitions and easier debugging over time
• When building systems that require composability, replayability, or snapshotting
• When refactoring object-heavy code toward simpler, data-focused designs

Best practices

• Prefer plain data structures (dicts, lists, sets) over custom objects unless identity is required
• Write small, pure functions that operate on immutable inputs and return new values
• Keep state explicit and centralized (a single state container) and mutate via controlled update functions
• Use declarative pipelines and composable transforms instead of interleaved imperative loops
• Validate shapes of data early (schema/spec) and fail fast with clear errors
• Isolate side effects (I/O, DB, network) so pure logic remains testable

Example use cases

• Refactor a class-based domain model into dicts + pure transformation functions for easier testing
• Design an application state store (single atom-like container) with controlled update functions and snapshotting
• Replace imperative data-processing loops with composable transform pipelines to avoid intermediate mutable state
• Implement undo/redo or historical snapshots by storing immutable states over time
• Introduce a small spec/schema layer to validate incoming messages or API payloads before processing