Design by Contract Skill

Analyze, document, and implement DBC (Design by Contract) in any language. Core rule: if the caller satisfies all preconditions, the routine must guarantee all postconditions and restore invariants. A violation is a bug.

The process

1. Understand the code

Read the relevant function(s), class, or module. Identify the inputs, outputs, and state mutations.

2. Elicit the contract

For each function, identify:

• Preconditions: What must the caller ensure? (valid ranges, non-null, initialized state, authenticated user, etc.)
• Postconditions: What does the function guarantee? (return value properties, side effects that happened, invariants restored)
• For classes/modules: Invariants — what is always true?

For the system or subsystem: Semantic invariants — what fundamental business rule must never break?

3. Express the contract

Express contracts in a way that matches the language and project context. Use language mechanisms for language-specific enforcement options.

4. Prioritize

Not every function needs an elaborate contract. Prioritize: public APIs, complex input constraints, hidden assumptions, correctness-critical code, and boundary code between your system and external libraries.

5. Document and implement

When adding contracts to existing code:

1. Start by adding comments documenting the contract (pre/post/invariants) — this helps clarify thinking
2. Add executable assertions where the language supports it
3. Consider type-level contracts (refinement types, newtypes, smart constructors) for stronger static guarantees
4. For semantic invariants, document them prominently (e.g., near the module/class definition or in a design doc)

6. Validate

After adding contracts:

• Run existing tests to verify the new assertions don't break current behavior
• Test with known-bad inputs to confirm the assertions fire as expected
• Check for false positives: a contract firing during normal operation means either the contract is wrong or there's a bug — determine which
• Crash early: when a contract is violated, raise an error immediately with a clear message. Don't silently return NaN/null/defaults. In long-running servers, terminate the request/transaction rather than the whole process.

How to present your analysis

When the user asks you to analyze code, structure your output like this:

## Contract Analysis: `functionName`

### Preconditions
- ✅ / ❌ / ⚠ (status) — description
  *Suggestion*: how to document/enforce this

### Postconditions
- ✅ / ❌ / ⚠ (status) — description
  *Suggestion*: how to document/enforce this

### Invariants
- ✅ / ❌ / ⚠ (status) — description
  *Suggestion*: how to document/enforce this

### Semantic Invariants (system-level)
- description of any overarching business rules

### Summary
Count of existing vs. missing contracts. Key recommendations.

Use:

• ✅ = contract exists and is correct
• ⚠ = contract exists but is incomplete or could be strengthened
• ❌ = contract is missing, incorrect, or violated

Example

User request:

"Here's a function that calculates the discount for a customer order. Can you add contracts?"

def apply_discount(order_total, customer_tier, items):
    if customer_tier == "gold":
        discount = 0.2
    elif customer_tier == "silver":
        discount = 0.1
    else:
        discount = 0.0
    return order_total * (1 - discount)

Response:

## Contract Analysis: `apply_discount`

### Preconditions
- ❌ `order_total` must be positive (currently unenforced)
  *Suggestion*: `assert order_total > 0, "order_total must be positive"`
- ❌ `customer_tier` must be one of "gold", "silver", "standard" (currently unenforced)
  *Suggestion*: `assert customer_tier in ("gold", "silver", "standard"), f"Unknown tier: {customer_tier}"`
- ❌ `items` must be a non-empty list of items (currently unenforced)
  *Suggestion*: `assert items, "items list must not be empty"`

### Postconditions
- ❌ Discount must be between 0 and order_total (result should be >= 0)
  *Suggestion*: `assert 0 <= result <= order_total, f"Result {result} out of range"`
- ⚠ `items` list should not be mutated (side effect free) — currently OK but should be stated

### Invariants
No class invariants — this is a standalone function.

### Summary
- **0** contracts documented
- **4** contract suggestions (3 preconditions + 1 postcondition)
- Key recommendation: start by asserting the precondition on `customer_tier` — this catches a real bug vector

References

• Language mechanisms — language-specific DBC enforcement options
• The Pragmatic Programmer (2nd ed.), Topic 23 — Design by Contract, by Dave Thomas and Andy Hunt
• Object-Oriented Software Construction (2nd ed.), by Bertrand Meyer
• Eiffel documentation on DBC: https://www.eiffel.org/doc/eiffel/Design_by_Contract