name: simplicity-principles description: Use when designing solutions, adding features, or refactoring by applying KISS, YAGNI, and Principle of Least Astonishment to write simple, predictable code. allowed-tools:

Read
Edit
Grep
Glob

Simplicity Principles

Write code that is simple, necessary, and unsurprising.

Three Core Principles

1. KISS - Keep It Simple, Stupid

Simple solutions are better than clever ones

What Simple Means

Readable by developers of varying skill levels
Fewer moving parts and abstractions
Direct and obvious implementation
Easy to debug and test
Minimal cognitive load

Elixir Examples

# COMPLEX - Over-engineered
defmodule PaymentCalculator do
  use GenServer

  def start_link(_), do: GenServer.start_link(__MODULE__, %{}, name: __MODULE__)
  def calculate(items), do: GenServer.call(__MODULE__, {:calculate, items})

  def handle_call({:calculate, items}, _from, state) do
    result = Enum.reduce(items, Money.new(:USD, 0), &Money.add(&2, &1.price))
    {:reply, result, state}
  end
end

# SIMPLE - Just a function
defmodule PaymentCalculator do
  def calculate(items) do
    Enum.reduce(items, Money.new(:USD, 0), &Money.add(&2, &1.price))
  end
end
# Use GenServer only when you need state/concurrency

# COMPLEX - Unnecessary abstraction
defmodule UserQuery do
  defmacro by_status(status) do
    quote do
      from u in User, where: u.status == ^unquote(status)
    end
  end
end

# SIMPLE - Direct query
def active_users do
  from u in User, where: u.status == "active"
end

def inactive_users do
  from u in User, where: u.status == "inactive"
end
# Macros only when you need metaprogramming

TypeScript Examples

// COMPLEX - Over-abstraction
class UserDataManager {
  private dataSource: DataSource;
  private cache: Cache;
  private transformer: DataTransformer;

  async getUser(id: string): Promise<User> {
    const cached = await this.cache.get(id);
    if (cached) return this.transformer.transform(cached);

    const raw = await this.dataSource.fetch(id);
    await this.cache.set(id, raw);
    return this.transformer.transform(raw);
  }
}

// SIMPLE - Direct approach
async function getUser(id: string): Promise<User> {
  const response = await fetch(`/api/users/${id}`);
  return response.json();
}
// Add cache/transform only when performance demands it

// COMPLEX - Clever but confusing
const isValid = (x: number) => !!(x >= 0 && x <= 100);
const process = (items: number[]) =>
  items.filter(isValid).reduce((a, b) => a + b, 0);

// SIMPLE - Clear intent
function calculateTotal(scores: number[]): number {
  const validScores = scores.filter(score => score >= 0 && score <= 100);
  return validScores.reduce((sum, score) => sum + score, 0);
}

KISS Guidelines

Prefer functions over classes (unless you need state)
Prefer explicit over implicit
Prefer boring over clever
Prefer standard library over custom solutions
Prefer clear names over short names
Prefer straightforward logic over "elegant" one-liners

When NOT to KISS

Performance-critical code (after profiling proves need)
Preventing code duplication (after third instance)
Enforcing constraints (types, validations)

2. YAGNI - You Aren't Gonna Need It

Don't implement features until you actually need them

Signs You're Violating YAGNI

"We might need this someday"
"Let me add flexibility for future use cases"
"I'll build a generic solution"
"This could be configurable"

Elixir Examples (YAGNI)

# YAGNI VIOLATION - Premature abstraction
defmodule NotificationService do
  def send(notification, opts \\ []) do
    provider = opts[:provider] || :default
    priority = opts[:priority] || :normal
    retry_strategy = opts[:retry_strategy] || :exponential
    callback = opts[:callback]

    # Complex routing logic for features we don't use yet
  end
end

# GOOD - Build what you need now
defmodule NotificationService do
  def send_email(to, subject, body) do
    Email.send(to, subject, body)
  end

  # Add SMS when we actually need it
  # Add priorities when we have the requirement
  # Add retries when we see failures
end

# YAGNI VIOLATION - Unused flexibility
defmodule User do
  schema "users" do
    field :email, :string
    field :settings, :map  # "For future configuration"
    field :metadata, :map  # "For anything we might need"
    field :flags, {:array, :string}  # "For feature flags"

    # None of these are used yet!
  end
end

# GOOD - Add fields when needed
defmodule User do
  schema "users" do
    field :email, :string
    # Add fields when requirements emerge
  end
end

TypeScript Examples (YAGNI)

// YAGNI VIOLATION - Premature generalization
interface DataFetcher<T, P extends object = object> {
  fetch(params: P): Promise<T>;
  cache?(params: P): Promise<void>;
  invalidate?(key: string): Promise<void>;
  prefetch?(params: P[]): Promise<void>;
  // We don't use cache, invalidate, or prefetch yet!
}

// GOOD - Start simple
interface DataFetcher<T> {
  fetch(params: object): Promise<T>;
  // Add methods when we need caching
}

// YAGNI VIOLATION - Configurable everything
interface ButtonProps {
  onClick: () => void;
  variant?: 'primary' | 'secondary' | 'tertiary' | 'ghost' | 'outline';
  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
  shape?: 'rounded' | 'square' | 'pill';
  shadow?: 'none' | 'sm' | 'md' | 'lg';
  animation?: 'fade' | 'slide' | 'bounce';
  // Design only uses 2 variants and 1 size!
}

// GOOD - Implement what designs require
interface ButtonProps {
  onClick: () => void;
  variant?: 'primary' | 'secondary';  // Only what we use
  // Add options when design requires them
}

YAGNI Guidelines

Implement features when you have a concrete use case, not a hypothetical one
Delete unused code immediately (it's in git)
Start with hardcoded values, extract constants when they vary
Build for today's requirements, refactor for tomorrow's
Question every "nice to have" and "might need"

Exceptions to YAGNI

Security features (implement defense in depth upfront)
Data migrations (plan schema carefully)
Public APIs (harder to change later)
Accessibility (build in from start)

3. Principle of Least Astonishment (POLA)

Code should behave the way users expect it to behave

What Makes Code Astonishing

Unexpected side effects
Inconsistent naming
Breaking conventions
Hidden behavior
Surprising return values

Elixir Examples (POLA)

# ASTONISHING - Updates AND returns different thing
def update_user(user, attrs) do
  Repo.update!(User.changeset(user, attrs))
  UserCache.invalidate(user.id)  # Side effect!
  :ok  # Returns :ok instead of updated user!?
end

# EXPECTED - Clear behavior
def update_user(user, attrs) do
  Repo.update(User.changeset(user, attrs))
  # Caller handles cache invalidation explicitly
end

# ASTONISHING - Function name lies
def get_user(id) do
  case Repo.get(User, id) do
    nil ->
      attrs = %{id: id, email: "#{id}@example.com"}
      Repo.insert!(User.changeset(attrs))  # Created user in a getter!
    user -> user
  end
end

# EXPECTED - Name matches behavior
def get_or_create_user(id) do
  case Repo.get(User, id) do
    nil -> create_default_user(id)
    user -> user
  end
end

TypeScript Examples (POLA)

// ASTONISHING - Function mutates input
function processTask(gig: Task): Task {
  gig.status = 'processed';  // Mutates input!
  gig.processedAt = new Date();
  return gig;
}

// EXPECTED - Pure function
function processTask(gig: Task): Task {
  return {
    ...gig,
    status: 'processed',
    processedAt: new Date(),
  };
}

// ASTONISHING - Inconsistent return types
async function getUser(id: string): Promise<User | null | undefined> {
  // Returns null sometimes, undefined other times, no pattern
}

// EXPECTED - Consistent return
async function getUser(id: string): Promise<User | null> {
  // Always null when not found
}

// ASTONISHING - Breaking conventions
interface Props {
  onPress?: () => void;      // React convention: onX
  clickHandler?: () => void;  // Different convention in same interface!
  onTapGesture?: () => void;  // Yet another name for same thing!
}

// EXPECTED - Consistent conventions
interface Props {
  onPress?: () => void;
  onLongPress?: () => void;
  onDoublePress?: () => void;
}

POLA Guidelines

Follow framework conventions (Phoenix, React, Relay)
Use clear, descriptive names that match behavior
Return what the function name promises
Keep side effects explicit or avoid them
Be consistent within the codebase
Match platform conventions (iOS, Android, Web)
Honor principle of least surprise in APIs

Examples of Good POLA in YourApp

Command handlers return {:ok, result} or {:error, reason} (consistent)
React components with onPress not onClick (platform convention)
Ecto changesets don't touch database (pure validation)
GraphQL mutations clearly named: createTask, updateTask, deleteTask

Application Checklist

Before implementing

Is this the simplest solution? (KISS)
Do we actually need this now? (YAGNI)
Will this behavior surprise users? (POLA)

During implementation

Prefer straightforward over clever
Implement only what's required
Follow established conventions
Name things accurately
Make side effects explicit

During code review

Is there a simpler approach?
Are we building speculative features?
Does the API behave as expected?
Are conventions followed?

Red Flags

KISS Violations

"Let me show you this clever trick..."
More than 3 levels of abstraction
Requires 10-minute explanation
Uses advanced language features unnecessarily

YAGNI Violations

"We might need this later..."
Unused parameters/options
Configurable everything
"Generic framework" for 2 use cases

POLA Violations

"Well, technically it does..."
Inconsistent naming
Hidden side effects
Surprising error conditions

Integration with Existing Skills

Works with

solid-principles: Simple implementations of SOLID patterns
boy-scout-rule: Simplify when improving code
test-driven-development: Simple code is easier to test
elixir-code-quality-enforcer: Credo flags complexity
typescript-code-quality-enforcer: Linting enforces consistency

Remember

"Simplicity is the ultimate sophistication." - Leonardo da Vinci

Prefer boring, proven solutions over novel approaches
Build incrementally based on actual requirements
Follow conventions so code behaves as expected
Delete speculative code immediately
Simple != simplistic (handle errors, edge cases properly)

simplicity-principles

$ インストール