reopt-module-contract

---
name: reopt-module-contract
description: When adding or replacing a module, tool, or function. API boundary design, external-system integration, defining an inter-agent interface. When you touch code whose input/output schema and refusal conditions are unclear.
---

# Module Contract

OCLS phase: **CONTRACT** · Declare the conditions, authority, and failure paths of an execution unit.

## Core rules

- Give every module an explicit contract: input schema, output schema, required authority, refusal conditions, and the shape of the failure response.
- The contract lives in both code and documentation; violations must be detectable at runtime.
- When replacing a module, validate contract compatibility first.
- Invest in the Agent-Computer Interface (ACI) the way you invest in human interfaces — apply Poka-yoke (constraints that make misuse hard).

## Judgment question

**Under what conditions must this module refuse or fail?**

## Application check

1. Are the input and output schemas declared?
2. What input must it refuse?
3. What is the failure-response shape? How does the caller detect it?
4. What is the required authority scope?

## Code example

```typescript
// ✅ A module with an explicit contract
interface GenerateReplyContract {
  input: {
    category: string;
    context: string;
    tone: "formal" | "casual";
    maxTokens: number;
  };
  output:
    | { ok: true; response: string; confidence: number; sources: string[] }
    | { ok: false; reason: "rejected" | "failed"; code: string };
  authority: { read: ["knowledge-base"]; write: [] };
  rejects: [
    "category === 'legal-advice'",
    "context.length > 10000",
    "PII detected in context",
  ];
}

async function generateReply(
  input: GenerateReplyContract["input"],
): Promise<GenerateReplyContract["output"]> {
  if (input.category === "legal-advice") {
    return { ok: false, reason: "rejected", code: "LEGAL_ADVICE" };
  }
  // ... execute
}
```

## Antipatterns

**Customer support**: running modules without contracts produces "we changed the LLM and the response format shifted, so the QA Agent can't parse it" or "the new module answers legal-advice questions, so compliance just opened a ticket."

**DevOps**: a deploy tool without a contract repeats environment-specific failures like "works in dev but missing authority in prod." Declare required authority, rollback conditions, and timeouts in the contract to guarantee consistency across environments.

## Invocation example

```
"Apply Module Contract to Response Agent's generate() function.
It currently returns a bare string with no contract.
Include refusal conditions (PII, legal advice) and failure modes
(confidence < 0.7) in the contract."
```

## Related patterns

- Responsibility Partitioning — every separated responsibility needs a contract
- Evaluation and Guardrails — runtime validation of contract violations