least-astonishment

ilude's avatarfrom ilude

Principle of Least Astonishment (POLA) - ensure code changes behave as users and developers expect. Activate when making code changes, refactoring, modifying APIs, renaming functions/variables, changing file structure, or reviewing proposed implementations. Guides predictable, convention-following changes.

⭐5stars🔀0forks📁View on GitHub🕐Updated Dec 30, 2025⬇️1downloads

When & Why to Use This Skill

This Claude skill implements the Principle of Least Astonishment (POLA) to ensure software development remains predictable, maintainable, and consistent. It assists developers in making code changes that align with established conventions, helping to eliminate hidden side effects, scope creep, and confusing API modifications during the refactoring and review process.

Use Cases

  • Refactoring Legacy Code: Ensuring that structural improvements do not introduce unexpected behaviors or break existing functional patterns that other developers rely on.
  • API Design and Evolution: Guiding the modification of functions and interfaces to ensure names accurately reflect behavior and return types remain consistent with user expectations.
  • Pull Request Management: Preventing 'scope creep' by identifying and separating unrelated changes, ensuring diffs remain focused and easy for team members to review.
  • Enforcing Coding Standards: Automatically checking new code against existing project naming conventions and architectural patterns to maintain a cohesive codebase.
  • Behavioral Change Documentation: Identifying when a necessary but 'surprising' change is being made and prompting the developer to provide clear explanations or seek explicit approval.
nameleast-astonishment
descriptionPrinciple of Least Astonishment (POLA) - ensure code changes behave as users and developers expect. Activate when making code changes, refactoring, modifying APIs, renaming functions/variables, changing file structure, or reviewing proposed implementations. Guides predictable, convention-following changes.

Principle of Least Astonishment (POLA)

Auto-activate when: Making code changes, refactoring, modifying existing functions, changing APIs, renaming things, moving files, or reviewing implementations. Should activate alongside development-philosophy for any non-trivial changes.

Core Principle

Every change should be predictable to someone familiar with the codebase.

If a change would surprise a developer who knows the project, either:

  1. Don't make it
  2. Make a smaller, less surprising change
  3. Explain clearly before proceeding

Before Making Changes

The Surprise Check

Ask yourself:

  1. Would this surprise someone reading a diff?

    • Unexpected file modifications
    • Unrelated changes bundled together
    • Renamed things without clear reason
  2. Does this follow existing patterns?

    • Check neighboring files first
    • Match naming conventions already in use
    • Use established abstractions, don't invent new ones
  3. Is the scope what was requested?

    • No unrequested refactors
    • No "improvements" beyond the ask
    • No adding features "while I'm here"
  4. Would the function/API do what its name suggests?

    • No hidden side effects
    • No surprising return values
    • No unexpected mutations

Common POLA Violations

❌ Scope Creep

Asked: "Fix the null check in validateUser"
Did: Fixed null check + refactored 3 other functions + added logging

Why surprising: Reviewer expects a small fix, gets a large diff.

❌ Hidden Side Effects

def get_user(id):
    user = db.find(id)
    user.last_accessed = now()  # Mutation in a "get" function
    db.save(user)
    return user

Why surprising: "get" implies read-only; this writes.

❌ Inconsistent Naming

# Existing codebase uses:
fetch_user(), fetch_orders(), fetch_products()

# New code adds:
retrieve_customer()  # Different verb AND different noun

Why surprising: Breaks established vocabulary.

❌ Unexpected File Changes

PR title: "Update README"
Files changed: README.md, config.py, utils.py, test_utils.py

Why surprising: Unrelated files modified.

❌ Silent Behavior Changes

# Before: returned empty list on error
# After: raises exception on error

Why surprising: Callers expecting old behavior will break.


POLA-Compliant Patterns

✅ Minimal Diffs

Change only what's necessary. If you notice something else that needs fixing, mention it separately.

✅ Match Existing Vocabulary

# Codebase uses "fetch_*" pattern
def fetch_payments():  # Follows convention
    ...

✅ Explicit Over Implicit

# Instead of hidden side effect:
def get_user(id):
    return db.find(id)

def get_and_update_access(id):  # Name reveals behavior
    user = db.find(id)
    user.last_accessed = now()
    db.save(user)
    return user

✅ Backward-Compatible Changes

# Adding parameter with default preserves existing behavior
def process(data, validate=True):  # Old callers unaffected
    ...

✅ Predictable Return Types

# Always return same type
def find_users(query) -> list[User]:
    # Return [] not None when empty
    return results or []

When Larger Changes Are Needed

Sometimes breaking POLA is necessary. When it is:

  1. Announce it - "This will change behavior for X"
  2. Explain why - "Current approach causes Y problems"
  3. Offer alternatives - "We could also do Z, which is less disruptive"
  4. Get explicit approval - Don't assume silence means consent

Quick Reference

Situation POLA-Compliant Approach
Fixing a bug Fix only that bug
Adding a feature Add only that feature
Refactoring Only when explicitly requested
Renaming Match existing conventions
Changing return types Add new function, deprecate old
Modifying APIs Backward-compatible by default

Integration with Other Principles

  • KISS - Simple solutions are usually less surprising
  • DRY - But don't create abstractions that surprise (premature DRY violates POLA)
  • Consistency - Following patterns is core to POLA

TL;DR

Do what the code reader expects. Match existing patterns. Keep changes focused. No surprises.