MADD Concepts

The Intention Document

The entry artifact. The starting point of every MADD cycle.

The Intention Document answers three fundamental questions:

• Why? — The business context, the problem to solve
• What? — What needs to be delivered, expected features
• How to know if it's successful? — Measurable validation criteria

Recommended structure

# Intention Document: [Feature Name]

## Context
Why this feature exists. The business problem it solves.

## Objective
What the user will be able to do once the feature is delivered.

## Requirements
- [ ] REQ-001: Requirement description
- [ ] REQ-002: Requirement description
- [ ] REQ-003: Requirement description

## Validation Criteria
- Criterion 1: How to verify REQ-001 is implemented
- Criterion 2: How to verify REQ-002 is implemented

## Out of Scope
What is NOT included in this intention.

## Dependencies
Prerequisites needed before starting.

Best practices

• One Intention Document = one coherent unit of work
• Each requirement must have at least one validation criterion
• The "out of scope" is as important as the scope
• The Intention Document is versioned with the code

The Executable Contract

The validation artifact. What transforms a wish into a verifiable commitment.

A contract is "executable" when it can be verified automatically. No "looks good" — it either passes or fails.

Contract types

The principle

If you can't write a test to verify a requirement, that requirement is poorly defined.

The executable contract is produced by the Spec Agent along with the Intention Document. The Dev Agent implements to satisfy the contract. The Audit Agent verifies contract compliance.

The Retro-Specification

The memory artifact. What objectively documents what actually exists.

The retro-spec is not what the developer says they did. It's what an independent agent (the Scribe) observes by analyzing the code.

Why it's different

Retro-spec contents

• Current state: What exists in the code
• Gaps: Differences between intention and implementation
• Technical debt: TODO, FIXME, identified workarounds
• Dependencies: Libraries, versions, constraints
• Attention points: Risks, known limitations

Usage

The retro-spec becomes the starting point for the next cycle. When new development begins, the Spec Agent consults the retro-spec to understand the real system state — not the marketing documentation.

The MADD Cycle

The three artifacts form a virtuous cycle:

1. Intention → Contract: The Spec Agent formalizes the need and defines success criteria
2. Contract → Code: The Dev Agent implements to satisfy the contract
3. Code → Audit: The Audit Agent verifies alignment
4. Code → Retro-Spec: The Scribe Agent documents reality
5. Retro-Spec → Intention: The next cycle starts from documented reality

Zero drift = each cycle is anchored in the previous one's reality.

Operations

The execution artifact. What defines how the system runs beyond development.

MADD doesn't stop at code delivery. The operations specification captures everything needed to deploy, run, and monitor the system in production.

What operations cover

Why operations matter in MADD

When AI accelerates development, the gap between "code works locally" and "system runs reliably in production" becomes the new risk. Specifying operations upfront — as part of the contract, not as an afterthought — ensures the Spec Agent thinks about deployment constraints and the Dev Agent builds with production in mind.