haskell-programmer

name	haskell-programmer
description	Review Haskell codebases emphasising functional programming idioms.

This skill specialises in reviewing Haskell codebases using modern functional programming idioms. It ensures clean, composable code; strong type safety; proper documentation; and adherence to best practices using tools such as HLint, Haddock, and (when relevant) Cabal/Stack conventions.

This skill enforces:

• Pure functional programming
• Clear function boundaries
• Small, composable definitions
• Proper type signatures
• Correct, structured documentation
• Clean-code principles appropriate for functional languages

Core Principles

Use "General Programming Review" guidelines as a base.

Coding Style

• Use 2 spaces for indentation.
• Limit lines to 80 characters.
• Use camelCase for variable and function names.
• Use PascalCase for type and data constructors.
• Use single characters for generic type variables (e.g., a, b, m).
• Use hlint to enforce style guidelines and suggest improvements.
• Use stylish-haskell for consistent formatting.
• All generated text output, including markdown content and descriptions, must adhere to an 80-column line limit. This applies to all content generated by the agent, not just code.

Functional Programming (FP) Foundations

• Encourage pure, total functions.
• Avoid partial functions (head, tail, fromJust, etc.) unless justified.
• Promote:
  • higher-order functions (map, foldr, foldl', traverse, sequence)
  • applicative/monadic patterns where appropriate
  • function composition ((.)) and pipelines
  • point-free style when it improves clarity
• Prefer algebraic data types and pattern matching.
• Encourage immutability and referential transparency.

Type Safety & Type System Usage

• Require explicit type signatures for top-level functions.
• Encourage:
  • newtypes over type synonyms when providing semantic meaning
  • sum types for branching logic rather than booleans or magic values
  • record syntax for clarity
  • deriving strategies (deriving stock, deriving newtype)
• Promote strong type design and small domain-specific types.

Clean Code & Architecture

• Functions should be small, focused, and composable.
• Modules should adhere to Single Responsibility Principle.
• Avoid:
  • deeply nested pattern matches
  • overly large case expressions
  • unnecessary monad stacks
  • mixing pure and effectful logic in the same function
• Prefer pure logic at the core and constrained effects at the boundaries.
• Suggest decomposition of complex monadic pipelines.

Documentation Standards (Haddock)

Every top-level function and type should include Haddock-style documentation:

• Summary description
• Parameter explanation via -- ^
• Return value description
• Example usage via >>>
• When applicable, document invariants and laws

Examples:

-- | Compute the average of a list of numbers.
average :: Fractional a => [a] -> a
average xs = sum xs / fromIntegral (length xs)

Build System (GNU Make)

When a Makefile is present in the project root, it must be used as the primary interface for development tasks. The agent should prefer running make commands over raw cabal or stack commands.

• Default Workflow: Running make (the default target) should perform formatting, checking, building, and testing (format check build test).
• Standard Targets:
  • make format: Format source files using cabal-fmt and stylish-haskell.
  • make check: Run linters and quality checks (e.g. hlint, cabal check, and generating tags).
  • make build: Compile the project.
  • make test: Execute the test suite.
  • make doc: Generate Haddock documentation.
  • make setup: Initialise the environment and dependencies.
  • make clean: Remove build artefacts.