Ambiguity Compiler

Turn vague software requirements into human-approved, testable behavioral contracts before an agent implements the wrong interpretation.

Comment

Ambiguity Compiler

Ambiguity Compiler turns vague software requirements into competing, testable contracts before Codex writes the wrong code.

Inspiration

Many software failures do not begin with incorrect code. They begin with a reasonable but unconfirmed interpretation of an ambiguous requirement.

Consider a request such as:

“Export the customer’s monthly transactions.”

Does “monthly” mean UTC, the customer’s local timezone, or the organization’s billing timezone? What happens at daylight-saving boundaries? Which records belong to the first and last day?

A developer—or an AI coding agent—can silently choose one interpretation, implement it correctly, and still ship the wrong behavior.

We wanted to introduce a missing compilation stage between natural-language requirements and implementation. Instead of immediately converting a request into code, Ambiguity Compiler exposes the decisions hidden inside it and asks a human to confirm the intended behavior.

What it does

Ambiguity Compiler transforms an underspecified requirement into a decision-ready workflow:

  1. The user submits a requirement and explicitly approved repository context.
  2. GPT-5.6 produces multiple plausible behavioral contracts.
  3. The contracts are compared by assumptions, invariants, edge cases, error behavior, and observable outcomes.
  4. The system asks targeted context questions when important information is missing.
  5. A human explicitly selects the intended interpretation.
  6. Ambiguity Compiler generates traceable contract-test specifications.
  7. Codex materializes those specifications in the target repository and runs verification.
  8. The system records a decision receipt connecting the original requirement, selected contract, tests, and sanitized verification result.

The goal is not to ask humans to approve every line of generated code. It is to place human approval at the highest-leverage moment: before an ambiguous product decision becomes implementation.

Product experience

The project includes three connected surfaces:

  • A responsive web application for compiling requirements, comparing alternatives, selecting a contract, and reviewing verification receipts.
  • An MCP server exposing the Ambiguity Compiler lifecycle as developer tools.
  • A reusable Codex plugin and skill that guides Codex through the workflow before implementing an ambiguous requirement.

The MCP workflow includes tools for compiling requirements, retrieving records, rendering alternatives, providing additional context, selecting an interpretation, generating tests, recording verification, and retrieving the final receipt.

How we built it

The web experience is built with React, TypeScript, TanStack Start, TanStack Router, and Vite.

The MCP service implements the compilation lifecycle over a local stdio transport. Inputs and outputs are schema-validated with Zod, and records are persisted locally for reproducible judge and developer sessions.

GPT-5.6 is responsible for the reasoning-intensive compilation stage. It receives only the requirement and explicitly scoped context, then produces structured candidate contracts. Deterministic application code validates the response, protects workflow transitions, and records verification metadata.

Codex drives the repository-level workflow. It helps inspect approved context, invoke the compiler, compare alternatives, materialize the selected contract as tests, run verification, and implement the behavior after human confirmation.

A no-key demonstration path and a golden timezone fixture are included so judges can experience the core workflow without configuring a production repository. The fixture intentionally demonstrates a failing UTC interpretation followed by a passing user-local-time interpretation.

How we used Codex

Codex was both a development tool and part of the final product experience.

During development, Codex helped us:

  • Design the contract and lifecycle schemas.
  • Build the web workflow and MCP tools.
  • Create the reusable plugin and skill.
  • Materialize executable test fixtures.
  • Run contract, MCP, plugin, lint, and production-build checks.
  • Audit the implementation against the product requirements.

Inside the product, the Ambiguity Compiler skill instructs Codex to follow this order:

scope context → compile → close context gaps → compare → confirm selection → materialize tests → verify → record receipt

This prevents an AI coding agent from silently implementing an unconfirmed interpretation.

Challenges we faced

The hardest challenge was ensuring that generated contracts represented genuinely different behavior rather than differently worded versions of the same idea.

We also had to balance useful repository context with privacy and security. Context is explicitly scoped, capped, and scanned for common secret patterns before live model analysis.

Another challenge was designing a coherent human-in-the-loop workflow. Confirmation must happen before test generation and implementation, while still keeping the experience fast enough to fit naturally into an AI-assisted development session.

Finally, integrating a web experience, an MCP lifecycle, a Codex plugin, structured model output, and executable verification into one hackathon prototype required careful scope management.

What we learned

We learned that ambiguity becomes much easier to discuss when it is converted into observable scenarios.

“Use the customer’s timezone” is an abstract statement. A test showing which records appear at a month boundary is concrete, reviewable, and falsifiable.

We also learned that human approval is most effective when it is placed at a decision boundary rather than at the end of a large code change. Once the contract is selected, Codex can move quickly while remaining aligned with the intended behavior.

Most importantly, AI coding reliability is not only a model-generation problem. It is also a requirements-compilation problem.

Accomplishments

We are proud that the prototype goes beyond simply rewriting requirements. It creates competing behavioral contracts, identifies consequential differences, supports explicit human selection, generates traceable test specifications, and records verification evidence.

We also packaged the workflow as an MCP-powered developer tool and reusable Codex skill, making the concept applicable beyond the demonstration UI.

What’s next

Next, we plan to add:

  • Shared multi-user project persistence.
  • Deeper GitHub and CI integrations.
  • Repository adapters for additional test frameworks.
  • Pull-request checks for unresolved ambiguity.
  • Team approval policies for high-risk decisions.
  • Historical analytics showing which requirement patterns cause the most rework.
  • Hosted workspaces for collaborative contract review.

Our long-term vision is for Ambiguity Compiler to become a standard safety layer between human intent and agent-generated code—similar to how type checking sits between source code and execution.

Built With

Share this project:

Updates