/sc-think-functional

name: sc-think-functional
description: >
  Reframe code design through functional programming principles for agent-assisted development. This skill SHOULD be used when the user says "think functional", "think FP", "make this pure", "separate effects", "where should this side effect go", "this function does too much", "how should I structure this for agents", "make this easier to review", "reduce context needed", or when planning module structure, store design, or code that agents will write and humans will review. Applies FP discipline within any language to maximize agent effectiveness and human reviewability.

Think Functional

FP discipline for agent-assisted development. Not about switching languages — about structuring code so agents write it well and humans review it fast.

Why FP Matters for Agents

<thesis>

**Agents are pattern matchers.** They compress training data into a world model, then map between representations: `f(pattern_in, context, constraints) => pattern_out`. FP makes the patterns explicit.

| FP Property | Agent Benefit | Human Benefit | | ------------- | --------------- | --------------- | | **Type signatures encode intent** | One line = full context. Input, output, effects. No retrieval needed. | Skim signatures, skip bodies | | **Pure functions are self-contained** | Entire function is contiguous text. No hidden state to chase. | Trust pure code, scrutinize edges | | **Composition is the architecture** | Agents pattern-match the wiring, generate the parts | Review wiring, ignore parts | | **Constraints prevent laziness** | Can't introduce side effects where the type system forbids them | Structural enforcement, not convention |

</thesis>

The Reframe

When approaching any design decision:

**Instead of:** "What object/class should own this behavior?" **Ask:** "What's the pure transform, and where does the effect happen?"

Every function is one of three things:

| Type | What It Does | Who Reviews | Agent Writes Well? | | ------ | ------------- | ------------- | ------------------- | | **Pure transform** | Data in, data out. No effects. | Skim or skip | Yes — self-contained, testable | | **Effect at the edge** | IO, network, DOM, persistence | Read every line | Needs guidance — effects are contextual | | **Composition** | Wires pure + edge together | This IS the architecture | No — human decides the wiring |

The Toolkit

Apply these operations to any code design problem:

<operations>

Separate: Pure from Impure

Ask: "If I deleted every side effect from this function, what computation remains?"

That computation is your pure core. Extract it. The side effects become a thin shell that calls the pure function and does IO with the result.

BEFORE: fetchUser(id) { data = await fetch(url); return validate(data); }
AFTER:  validateUser(data) { ... }  // pure
        fetchUser(id) { data = await fetch(url); return validateUser(data); }  // edge

Push Effects Outward

Ask: "Can the caller handle this effect instead of the callee?"

Effects belong at the outermost layer possible. Pushing the read out of the callee turns the function pure and lets the caller — who already knows the context — supply the data.

// BEFORE: callee reads localStorage; can't be tested without a DOM mock
function renderTheme(): string {
  const prefs = JSON.parse(localStorage.getItem("prefs") ?? "{}");
  return prefs.dark ? "dark" : "light";
}

// AFTER: caller reads, callee computes; pure function, trivial test
function renderTheme(prefs: { dark?: boolean }): string {
  return prefs.dark ? "dark" : "light";
}
// at the edge:
const prefs = JSON.parse(localStorage.getItem("prefs") ?? "{}");
renderTheme(prefs);

Make Illegal States Unrepresentable

Ask: "Can the type system prevent this bug, or does it rely on runtime discipline?"

Three encodings cover most real bugs — branded types for confusable values, `Result<T, E>` for fallible computation, and exhaustive `switch` for finite sums.

// (a) Branded type + smart constructor — raw strings can't reach UserId-typed APIs
type UserId = string & { readonly __brand: "UserId" };
const UserId = (raw: string): UserId | null =>
  /^u_[a-z0-9]{8}$/.test(raw) ? (raw as UserId) : null;

// (b) Result<T, E> — failure is in the return type, not in exceptions
type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };
const parseAge = (s: string): Result<number, "NaN" | "Negative"> => {
  if (s.trim() === "") return { ok: false, error: "NaN" }; // Number("") === 0 — guard first
  const n = Number(s);
  if (Number.isNaN(n)) return { ok: false, error: "NaN" };
  if (n < 0) return { ok: false, error: "Negative" };
  return { ok: true, value: n };
};

// (c) Exhaustive switch — adding a new variant becomes a compile error
type Shape = { kind: "circle"; r: number } | { kind: "square"; side: number };
const area = (s: Shape): number => {
  switch (s.kind) {
    case "circle": return Math.PI * s.r ** 2;
    case "square": return s.side ** 2;
    default: { const _: never = s; throw new Error(`Unhandled: ${JSON.stringify(_)}`); }
  }
};

Enforce Through Structure, Not Convention

Ask: "If an agent ignores my instructions, does the code still work correctly?"

Agents are lazy. They'll take shortcuts if shortcuts compile. Convention says "don't put side effects here." Structure says "this module physically cannot import the side-effect library." Prefer structure. Stack two real mechanisms — editor-time lint plus a build/CI