State Gap Mapper

Find the behavior your feature spec forgot before it becomes a bug.

Comment

Inspiration

Most feature specifications explain the happy path. The expensive bugs appear in the moments the document never resolves: What happens if a customer cancels while payment is processing? Can an approval be withdrawn after publishing starts? What should an expired verification code do?

Those are product decisions, but they are often discovered only after engineering or QA has already paid the cost. I built State Gap Mapper to surface those missing decisions while the feature is still a Spec.

What it does

State Gap Mapper turns a plain-English feature flow into an inspectable behavior map.

  1. Paste or import a Spec, or open one of three instant sample projects.
  2. GPT-5.6 extracts states, events, transitions, and sentence-level Evidence.
  3. Deterministic TypeScript evaluates the full state-by-event matrix, marks final-state cells as not applicable, and lists every missing transition from a non-final state.
  4. Undefined outcomes appear as red Structural Gaps, each linked to the exact words that created the question.
  5. A reviewer accepts a gap and chooses its target, or dismisses it as intentional.
  6. An accepted decision becomes a live transition and a deterministic Given/When/Then Test Stub.

Reviewers can also download a Markdown report or a lossless JSON project and reopen it later. No account is required, and the three cached samples run without an API call.

The trust model

The central design decision is a strict boundary between AI judgment and deterministic guarantees.

GPT-5.6 handles semantic work: understanding the prose, extracting the state machine, ranking which undefined outcomes are most relevant, explaining why they matter, and suggesting events the Spec may not have considered.

TypeScript remains authoritative for runtime validation, the complete Structural Gap set, Evidence composition, coverage changes, and Test Stub generation. Ranking changes the order, the rationales, and the suggested targets. It cannot invent a Structural Gap in the current map, remove one, or hide one. Extraction quality still matters, because the model decides the initial states, events, and transitions that the gap set is computed from. That is why the canvas is editable and sentence coverage is shown: both make the model's reading reviewable, and every edit recomputes the gaps deterministically. Suggested Events are shown separately in amber because they are possibilities, not computed facts.

The human stays in control of every behavior change.

How I built it

The interface uses React, TypeScript, Vite, React Flow, and Zustand. A Vercel serverless endpoint calls GPT-5.6 with structured outputs. Strict runtime decoders validate both model responses before application state changes. Sequence and revision guards prevent stale extraction or ranking responses from overwriting newer work.

The gap engine computes missing transitions from the validated machine, then layers ranking metadata on top. Import/export runs in the browser with strict versioned JSON validation, deterministic recomputation, safe filenames, and no project database.

How Codex accelerated the work

Codex was the implementation partner from the domain model through production verification. It accelerated the strict decoders, event taxonomy, deterministic gap engine, editable canvas, async state guards, component tests, import/export workflow, production debugging, Vercel release, and the reproducible Remotion demo.

I directed the product positioning, architecture decisions, two-tier honesty model, redline visual language, and the rule that every AI claim must remain inspectable. The repository records those decisions in ADRs and implementation plans.

The build used focused test-driven development and finished with 232 passing tests across domain logic, API boundaries, state management, components, and file transfer. Codex also helped diagnose a production-only Node ESM failure that did not appear in the local Vite build.

Challenges and lessons

The hardest challenge was making the deterministic claim honest. A deterministic gap engine can only analyze the machine it receives, so the interface also exposes coverage differences when source sentences are not mapped. Traceability matters as much as the finding.

A second challenge was keeping a complete matrix useful rather than overwhelming. GPT-5.6 ranks the findings for attention, but the deterministic layer preserves the full set.

The third challenge was coherence under asynchronous work. Novel Specs trigger extraction and ranking, while users can edit, accept, dismiss, or switch samples. Explicit session and machine revisions ensure late responses cannot corrupt the active result.

Try it

The hosted app runs in a current desktop browser. Choose the checkout sample, inspect the red processing x cancel gap, open its Evidence, accept it with Cancelled as the target, and copy the generated Test Stub. The full judging flow is free and requires no account.

For local development, run npm ci and npx vercel dev. An OpenAI API key is needed only for mapping a novel Spec locally. The public repository includes setup instructions, sample data, architecture records, tests, and reproducible demo source.

What's next

The next step is to bring this review loop into team workflows: domain-specific packs for payments and approvals, shared decision memory, and GitHub or issue-tracker integration that catches behavioral gaps before implementation begins.

Built With

Share this project:

Updates