Before the Agent Runs

A Migration Running for Twenty Years

There has been a slow migration happening in software development — not in any one release, not announced by any team — but visible in the pattern of what three disciplines have each moved: the definition of correctness upstream.

Test-Driven Design moved correctness upstream from debugging to implementation. Behaviour-Driven Design moved it upstream from implementation to behaviour specification. Domain-Driven Design moved it upstream from feature specifications to the domain model itself. Each discipline said the same thing in a different register: the later you discover that an assumption was wrong, the more it costs.

GDD is not a replacement for TDD, BDD, or DDD. It is their upstream completion — the discipline that defines correctness at the layer that precedes all three. A governed constraint set is what exists before the domain model is drawn, before the behaviour specification is written, before the first test is named. GDD says: before any of that runs, there are assumptions. Formalize them. Stress them. Surface what you cannot resolve. Those unresolved items are not failure. They are the most important output the pre-build session produces.

A note on DDD: Domain-Driven Design addresses domain model integrity and bounded context separation — a different layer from GDD. DDD asks how to represent the domain accurately once it is understood. GDD asks whether the domain is understood accurately enough to represent at all. They are complementary, not competing. The tension DDD practitioners recognize in “getting the domain model wrong” is exactly the problem GDD operates on, one layer upstream.

The Governance-Last Problem

AI-first delivery is fast. Agents generate code, schemas, database migrations, API contracts, and compliance logic at a pace that outstrips the capacity of any review process to catch assumptions before they become behavior.

The instinct is governance-last: produce the artifacts, then review them. Catch problems in code review. Fix them in testing. Audit after deployment if necessary. This is the pattern software development has run on for decades, and it works reasonably well when artifacts are small, the domain is well-understood, and the cost of an incorrect assumption is manageable.

Neither of those conditions holds in AI-first delivery. Agents generate large artifacts quickly. The domain is often partially understood — that is frequently why an AI agent is being used rather than a developer who could hold the context manually. And the cost of an incorrect assumption in compliance logic, lending decisions, or multi-agent procurement workflows is not manageable: it is a regulatory notification, a production rollback, or a financial exposure that nobody saw coming because it was never in the spec.

Governance-last is not wrong. It is late. GDD proposes governance-first: formalize the assumptions before the agent runs, stress-test them until the ones that cannot be resolved surface cleanly, and make the human decisions that need to be made before the machine begins. The cycle that does this is the Iterative Constraint Refinement cycle.

The ICR Cycle

The Iterative Constraint Refinement (ICR) cycle runs six steps. Its exit condition is not “all constraints resolved.” It is “all residue explicitly acknowledged with an owner.” The cycle is designed to surface what it cannot resolve — not to eliminate uncertainty, but to name it and assign it before execution begins.

What the Statuses Mean

Every constraint in the governed constraint set carries a status. Each status is a directive — a specific instruction to the agent executing against the set:

The statuses make the governed constraint set operational across two contexts: a human preparing to build, and an AI agent executing the build. A CLAUDE.md template can point an agent at the .gdd/ folder so it reads the constraint set before generating anything. The statuses become runtime directives: proceed, flag, stop, surface.

What One Example Revealed

A bank preparing to run a Phoenix legacy modernization pipeline against a 40-year-old COBOL loan origination system. 180,000 lines. The original authors have retired. The instinct: start Phoenix immediately. Extract the business logic. The code is the source of truth.

GDD says: not yet.

Three of the eight formalized assumptions produce immediate conflicts when the CHECK step runs.

[1]  We believe a loan is approved when DTI ratio is below 43%.
[3]  We believe employment is verified by a flag in the APPLICANT table.
[4]  We believe the approval path handles self-employed applicants.
[6]  We believe the 43% DTI threshold is a fixed regulatory requirement.

[CONFLICT A]  Statement [6] assumes regulatory fixed floor.
              Statement [1] uses 43% as if it is policy-adjustable.
              These cannot both be true — different governance implications.

[CONFLICT B]  Statement [3] assumes the flag covers all applicants.
              Statement [4] assumes self-employed are handled.
              If self-employed have no flag path, [4] cannot be true.

ITEM 1: Is the 43% DTI threshold regulatory or policy?
  Cannot resolve from: COBOL code (encodes the number, not its origin)
  Decision required: Chief Compliance Officer
  Consequence if wrong: regulatory breach vs. unnecessary constraint

ITEM 2: What is the self-employed applicant path?
  Cannot resolve from: COBOL code (branch reaches a subroutine
                       referencing a 1987 product that no longer exists)
  Decision required: Head of Loan Origination + Compliance

ITEM 3: Are reason codes current?
  Cannot resolve from: COBOL code (hardcoded integers, not mapped)
  Decision required: Operations + Compliance

The GDD cycle ran four hours across two working sessions with five people. Three gate decisions were made before Phoenix ran a single agent pass. The CCO confirmed the 43% threshold was regulatory — immutable, not policy-adjustable. The Head of Loan Origination scoped self-employed applicants out of the initial migration. Operations took ownership of mapping the reason codes to current regulations.

None of those decisions were visible in the COBOL code. The code encoded the behavior. The GDD cycle encoded the intent behind the behavior — and surfaced the items where that intent was either missing or contradictory. The alternative — discovering the self-employed branch ambiguity in production — would have triggered a regulatory notification and a forensic investigation of how many applicants were incorrectly processed during the migration window.

The Most Valuable Output

A GDD cycle produces something that looks, at first glance, like a failure list. Conflicts found. Items that could not be resolved. Decisions that need to be made by people who are not in the room. It is tempting to interpret this as evidence that the team did not know enough to proceed.

The opposite is true. The constraints you could not resolve are precisely the constraints that were most likely to produce production incidents, regulatory notifications, or silent logic failures. The COBOL self-employed branch was not a bug in the usual sense. It was a 40-year-old decision encoded in a subroutine referencing a product that no longer existed. There was no test for it. There was no documentation of it. There was no Phoenix agent smart enough to know it should not be replicated.

The unresolvable residue is not a symptom of insufficient preparation. It is the evidence that the preparation was real. An assumption set that produces no residue either contains assumptions that are genuinely and completely resolved — which is rare in any nontrivial domain — or it contains assumptions that were never stressed hard enough to surface what they depended on.

The exit condition for the ICR cycle is not “all constraints resolved.” It is “all residue explicitly acknowledged with an owner.” That formulation is precise. An acknowledged unresolved item with a named owner and a deadline is a governed risk. An unacknowledged assumption is an ungoverned one. The difference, in production, can be a regulatory breach.

Making Agents Governance-Aware

GDD produces a governed constraint set. Making an AI agent use it is a one-step operation: drop a CLAUDE.md file in the project root and point it at the .gdd/ folder.

The template instructs the agent to read three files before generating anything:

Before writing any implementation code, any schema,
any configuration, or any test — read the GDD layer:

  1. Read .gdd/CONSTRAINTS.md   — the governed constraint set
  2. Read .gdd/RESIDUE.md       — open items requiring human decision
  3. Read .gdd/GATES.md         — human decisions already made

→ Does any [UNKNOWN] or [CONFLICT] item in RESIDUE.md
  affect what I am about to generate?

  If YES  — surface it to the human before proceeding.
            Do not generate code that depends on an unresolved item.

  If NO   — proceed, and note which constraints govern your output.

The .gdd/ folder holds four files: CONSTRAINTS.md (the primary artifact), RESIDUE.md (open items), GATES.md (recorded gate decisions), and a CYCLES/ directory for append-only ICR cycle history. The agent reads the constraint set on every pass. A [RESOLVED] item is implemented exactly as stated. An [UNKNOWN] item causes the agent to stop and surface the question rather than resolve it silently. An [CONFLICT] item stops both sides of the implementation until the human resolves it.

This step — making the agent governance-aware via CLAUDE.md — is separable from the ICR cycle itself. A team that has not run a full ICR cycle can still initialize a minimal constraint set and build with governance visibility from day one. The cycle can run alongside early implementation as assumptions surface, rather than only before a major migration or greenfield build.

Where GDD Sits

The Semantic Intent ecosystem runs on a chain that begins with governed intent and ends with auditable execution history. GDD is the upstream source:

The Synthesis Gate (DOI 10.5281/zenodo.20684283) is the downstream complement to GDD. GDD surfaces residue before the machine runs. The Synthesis Gate handles residue that emerges during execution — ambiguity the agent encounters that requires human judgment at the moment it arises. Together they describe a complete governance model for AI-first delivery: formalize what is known before build, surface what is unknown during build. Neither eliminates ambiguity. Both ensure it is named and owned.

Intent-as-Infrastructure (DOI 10.5281/zenodo.20681523) named the human as a first-class architectural primitive — not a safety valve, but a designed-in endpoint. GDD operationalizes that claim at the pre-execution layer. The human decisions that need to be made before any agent runs are not a bottleneck to route around. They are the governance acts that make the machine's execution meaningful.

Go deeper