19.3 Fixing with guardrails: tests, assertions, and contracts

Goal: smallest safe fix + regression lock

Incident fixes should be:

• small (minimal diff),
• targeted (fix the confirmed root cause),
• verified (tests and smoke checks),
• locked (regression test so it can’t return silently).

The guardrailed fix workflow

1. Confirm the cause: one hypothesis is supported by evidence.
2. Add regression test: fails before fix.
3. Implement minimal fix: diff-only; small scope.
4. Run tests: targeted subset + full suite if possible.
5. Smoke check: reproduce the original failure and confirm it’s gone.
6. Roll out safely: staged rollout or revert plan ready.

Regression tests (the lock)

A regression test is the “never again” contract. Good regression tests are:

• minimal,
• deterministic,
• named after the bug/behavior,
• close to the root cause.

If you can’t add a test immediately (rare), at least add a repeatable check and create a follow-up task to add the test.

Assertions and contracts (prevent future weirdness)

Many incidents come from “impossible states” becoming possible. Add guardrails:

• validate inputs at boundaries
• assert invariants (non-null, non-empty, expected ranges)
• use schema validation for structured outputs
• turn silent failures into explicit errors

These checks turn future incidents into fast failures with clear signals.

Diff discipline during incidents

Enforce strict diff rules:

• diff-only changes
• file scope limit
• no unrelated formatting or refactors
• line budget (“stop if diff exceeds N lines”)

If the model produces a large patch, reject it and ask for a smaller fix.

Verification and rollout safety

Before shipping:

• run tests
• run the original reproduction
• check error rates and latency in staging (if available)
• roll out gradually (if possible)
• have a rollback/revert plan ready

Copy-paste prompts

Prompt: minimal fix with regression test

We have a confirmed root cause and a regression test.

Constraints:
- Implement the smallest fix possible
- Diff-only changes
- Do not refactor unrelated code
- Do not weaken the regression test

Context:
- Failing test output: ...
- Relevant files: ...

Output:
- Unified diff only
- Then list verification commands

Prompt: add boundary validation/guards (optional)

Add minimal boundary validation/assertions to prevent this class of bug.

Constraints:
- Keep changes small
- Preserve behavior except for rejecting invalid states
- Diff-only changes
- Add tests for the new validation behavior

Where to go next

• 19.4 Postmortems
• 19.5 Preventing recurrence