ai-development-team-agent-pack/.ai/skills/design-by-contract.md

Skill — Design by Contract

Purpose

Create work with explicit preconditions, postconditions, invariants, and failure modes so agents and humans can reason about behavior before implementation.

Principles

• Prefer explicit contracts over implied behavior.
• Make inputs, outputs, side effects, and errors visible.
• Define the boundaries before writing code.
• Keep contracts short enough to scan and test.
• Treat contract violations as bugs, not surprises.
• Align tests, documentation, and implementation to the same contract.
• Treat the Product Owner as the final authority.

Process

1. Identify the callable boundary, user action, or document being created.
2. Write the contract:
   • Preconditions
   • Inputs and types
   • Outputs and success criteria
   • Postconditions
   • Invariants
   • Failure modes
   • Side effects
3. Check whether any assumption is unstated or ambiguous.
4. Convert the contract into acceptance criteria or checks.
5. Implement or document only after the contract is clear.
6. Validate the result against the contract.

Best Practices

• Use numbered or bulleted contracts for quick review.
• State what must be true before work starts.
• State what must be true when work finishes.
• Call out any data ownership or persistence expectations.
• Include error handling and retry expectations when relevant.
• Prefer contract tests for public interfaces and workflows.
• Record contract changes in the relevant documentation or story.

Contract Checklist

• Preconditions are stated.
• Inputs are named and bounded.
• Outputs or deliverables are defined.
• Invariants are clear.
• Failure modes are described.
• Side effects are explicit.
• Tests or validation steps map to the contract.
• The Product Owner can review the result without guessing.

Anti-Patterns

• Hidden assumptions.
• “It should just work” requirements.
• Implementing before the boundary is clear.
• Testing behaviors no one asked for.
• Documentation that does not match the implementation.

Output Standard

Outputs should be:

• Complete enough to implement against
• Concise enough to review quickly
• Structured in Markdown
• Easy to turn into tests
• Easy to update when the contract changes

---

Self-Evolution Protocol

This file is allowed to improve over time, but only through a controlled change process.

When to propose an update

An agent may propose an update when it learns:

• A recurring mistake should be prevented.
• A better workflow has been proven useful.
• A project-specific convention has become stable.
• A prompt pattern produced better results.
• A tool, framework, library, or deployment rule changed.
• The Product Owner approved a new standard.

How to update this file

Agents must not silently rewrite this file. They must create an improvement proposal using:

./.ai/evolution/improvement-proposal-template.md

Every proposal must include:

• File to update
• Current problem
• Proposed change
• Reason
• Risk
• Rollback plan
• Product Owner approval status

Learning Log

Add durable lessons here only after they are proven useful.

Date	Lesson Learned	Change Made	Approved By
YYYY-MM-DD	Initial baseline created.	Created file.	Product Owner