What is a Behavior Contract?

A Behavior Contract is a formal, testable description of a bug, including how it is triggered (Bug Condition), the expected outcome after a fix (Postcondition), and the aspects that must remain unchanged (Invariants).

What are Bug Condition, Postcondition, and Invariants?

Bug Condition defines the triggering inputs or state; Postcondition defines the correct post-fix behavior; Invariants describe ongoing constraints that must not break during the fix.

How does it help bugfix workflow?

It provides a structured, testable specification that guides failure reproduction, test generation, and minimal-risk fixes, increasing clarity and QA coverage during bug remediation.

behavior-contract

Scanned

npx machina-cli add skill a5c-ai/babysitter/behavior-contract --openclaw

Files (1)

SKILL.md

2.3 KB

behavior-contract

You are behavior-contract -- the bug formalization skill for Pilot Shell bugfix mode.

Overview

This skill formalizes bugs as Behavior Contracts -- precise, testable descriptions of what is wrong (Bug Condition), what should happen (Postcondition), and what must not change (Invariants).

Contract Structure

Bug Condition

The exact input, state, or sequence that triggers the bug. Must be specific enough to write a failing test.

Example: "When processPayment() receives an amount of exactly $0.00, it throws an unhandled TypeError instead of returning a zero-amount receipt."

Postcondition

The correct behavior that must hold after the fix is applied.

Example: "When processPayment() receives $0.00, it returns a valid Receipt object with amount: 0 and status: 'completed'."

Invariants

Existing correct behaviors that must be preserved by the fix.

Example:

"Positive amounts still process correctly"
"Negative amounts still throw InvalidAmountError"
"Receipt format remains unchanged for all amount types"

Contract Document Template

# Behavior Contract: [Bug Title]

## Bug Condition
[Precise description of triggering conditions]

## Postcondition
[Expected correct behavior after fix]

## Invariants
- [ ] Invariant 1: [existing behavior to preserve]
- [ ] Invariant 2: [existing behavior to preserve]

## Testable Assertions
1. `expect(processPayment(0)).toEqual({ amount: 0, status: 'completed' })`
2. `expect(processPayment(100)).toEqual({ amount: 100, status: 'completed' })`
3. `expect(() => processPayment(-1)).toThrow(InvalidAmountError)`

Usage in Bugfix Workflow

Bug analysis identifies root cause at file:line
This skill formalizes the contract from the analysis
tdd-enforcer writes failing test from Bug Condition
tdd-enforcer writes preservation tests from Invariants
Minimal fix applied, contract audited

Source

git clone https://github.com/a5c-ai/babysitter/blob/main/plugins/babysitter/skills/babysit/process/methodologies/pilot-shell/skills/behavior-contract/SKILL.md

View on GitHub

Overview

Behavior Contracts formalize bugs as precise, testable artifacts: Bug Condition, Postcondition, and Invariants. This framing helps reproduce failures, define expected outcomes, and preserve correct behavior across fixes, with a template and testable assertions to guide QA.

How This Skill Works

Define the Bug Condition as the exact triggering input or state. Specify the Postcondition as the correct outcome after the fix. List Invariants that must remain true despite changes. Use the Contract Document Template to capture these sections, and rely on a tdd-enforcer to generate failing tests from the Bug Condition and preservation tests from Invariants before applying a minimal fix.

When to Use It

When you need to isolate a bug's trigger to enable regression tests.
When fixing a function with critical invariants that must be preserved.
When you want explicit, testable documentation of the bug and its intended fix.
When coordinating bugfix efforts across multiple team members or tools.
When validating fixes with concrete success criteria tied to Bug Condition and Invariants.

Quick Start

Step 1: Analyze the bug and draft a Behavior Contract describing Bug Condition, Postcondition, and Invariants.
Step 2: Use tdd-enforcer to generate failing tests from the Bug Condition and preservation tests from Invariants.
Step 3: Implement the minimal fix and audit the contract against the changes.

Best Practices

Capture a precise Bug Condition with exact inputs, state, and sequence.
Write a clear Postcondition that defines the expected correct outcome.
Enumerate all Invariants that must not change across fixes.
Use the Contract Document Template to maintain consistency across bugs.
Link tests directly to the Bug Condition and Invariants for traceability.

Example Use Cases

Bug Condition: When processPayment() receives an amount of exactly $0.00, it throws an unhandled TypeError instead of returning a zero-amount receipt.
Postcondition: When processPayment() receives $0.00, it returns a valid Receipt object with amount: 0 and status: 'completed'.
Invariant 1: Positive amounts still process correctly.
Invariant 2: Negative amounts still throw InvalidAmountError.
Invariant 3: Receipt format remains unchanged for all amount types.

Frequently Asked Questions

Add this skill to your agents