defensive

Files (1)

• SKILL.md

SKILL.md (first lines)

# Defensive Programming: Never Trust the Input

Software fails because something arrived that the code did not expect. A null where an object
was assumed, a string where a number was assumed, a value outside the range the arithmetic
relies on, a service that returned an error instead of a payload.

The defensive discipline is to assume none of it. Every function treats its callers as
unreliable, every boundary is checked, every external call is wrapped, and every failure path
has a defined behaviour rather than an exception escaping into the user's face.

**The line that does most of the work:**

> An unhandled failure is a defect you shipped to the user. A handled failure is one you
> chose the behaviour for. Wherever your code touches something it did not construct, decide
> now what happens when that thing is wrong, because the alternative is finding out in
> production.

## The five disciplines

**Validate at every boundary.** Any value crossing into your code from elsewhere is
untrusted: HTTP requests, config files, environment variables, database rows, other modules'
return values. Check type, range, shape and required fields before use. Validation duplicated
at several layers is not waste; it is depth, and it means one missed check does not become a
defect.

**Guard against absence.** Null, undefined, empty string, empty list, missing key and zero
are all values a caller can hand you. Check for them explicitly before dereferencing, and
decide what absence means here: an error, a skip, or a default.

**Supply safe fallbacks.** When a value is missing or invalid, prefer continuing with a
sensible default over aborting. A report that renders with a zero in one cell serves the user
better than a stack trace. Choose the default that fails toward the least harm.

**Catch, log, continue.** Wrap operations that can throw. Log enough context to diagnose it
later: the inputs, the operation, the error. Then decide whether this frame can proceed. An
exception that escapes several frames loses the context that would have explained it.

**Degrade rather than fail.** A dependency being down should reduce functionality, not remove
it. Cache the last good value, disable the feature, show a partial result. Total failure
should be reserved for cases where continuing would be worse than stopping.

## How to work

1. **Enumerate what can arrive.** For each input, list the values a hostile or careless caller
   could supply, including the ones the type nominally forbids.
2. **Decide the behaviour for each.** Reject, substitute, skip or propagate. Write the decision
   down where the code shows it.
3. **Push checks outward and inward.** Validate at the entry point so bad data is caught early,
   and check again deeper down so a new caller cannot bypass it.
4. **Make failures visible without making them fatal.** Log at the point of detection, with the
   value that caused it.
5. **Test the unhappy paths.** Null, empty, oversized, wrong type, wrong encoding, and the
   dependency being unavailable.

## Routing

Read the sub-skill matching the work, then follow it. If more than one applies, read both; if
none clearly applies, continue with this document.

| Sub-skill | Use for |
|---|---|
| `design` | Designing a new interface, module, schema or type, with its validation and failure behaviour. |
| `audit` | Reviewing existing code for unchecked inputs, unguarded dereferences and unhandled failure paths. |
| `retro` | Something broke; adding the checks and handling that would have contained it. |
| `ux` | Forms and flows. Input validation, error messaging, and recovering from user mistakes. |
| `authz` | Permission checks, and what to do when identity or permission data is missing or malformed. |
| `data` | Pipelines and queries. Handling missing rows, nulls, schema drift and malformed records. |
| `ops` | Deploys, migrations and configuration. Handling absent config, failed steps and partial state. |
| `guardrails` | Lint rules and CI checks that catch unvalidated input and unhandled exceptions. |
| `agent-guardrails` | Constraining an AI assistant's actions, and handling what it does wrong. |
| `llm` | Model API calls. Handling malformed output, refusals, timeouts and unexpected shapes. |

## What good output looks like

Specific about the value, the boundary and the chosen behaviour.

- **Name the input and what could be wrong with it.** "`user_id` may be absent when the session has expired" is actionable; "validate inputs" is not.
- **State the fallback and why it is safe.** A default is a decision, so say what it costs when it fires.
- **Cover the dependency being unavailable**, not only the value being wrong.
- **Show the guard in place.** A three-line before-and-after communicates the shape faster than describing it.
- **Order by blast radius.** An unchecked value that reaches a write matters more than one that reaches a log line.

## What to avoid

**Silent swallowing.** `except: pass` removes the failure from view without handling it. If a
failure is genuinely ignorable, log it and say why in a comment.

**Validating without deciding.** Checking a value and then using it anyway is worse than not
checking, because the check implies coverage that does not exist.

**Fallbacks that hide a real problem indefinitely.** A default that fires every request is not
resilience, it is an outage nobody noticed. Fallbacks should be observable.

**Over-broad catches around large blocks.** Wrapping fifty lines in one handler means you
cannot tell which of the fifty failed, and recovery cannot be specific to the failure.

**Guard clauses that never fire.** A check for a condition the type system already excludes
adds noise and suggests the author did not know what the type guaranteed.

## What it looks like in practice

A worked example, because "validate your inputs" is easy to agree with and hard to apply.

Here is a function that works until it does not:

```python
def send_invoice(order, customer, config):
    total = order["amount"] * config["tax_rate"]
    email = customer["email"]
    body = render_template(config["template"], total=total)
    mailer.send(email, body)
    return True
```

Every line trusts something it did not construct:

**`order["amount"]` assumes the key exists and is numeric.** A missing key raises `KeyError`
several frames from the caller who could have explained it; a string raises `TypeError` from
inside the arithmetic.

From rainmanjam/poka-yoke, MIT.

More from rainmanjam/poka-yoke