Quick answer: AI fills gaps with small per-handler slices tied to specific gap codes, but it cannot invent a route, method, or path. The deterministic scan first proves the structure through framework tracing and AST analysis, leaving only explicit unknowns. The model then addresses those named gaps, rather than generating routes from imagination, and every AI contribution stays bounded to a handler and a gap code.
Why the model is not allowed to invent routes
A model that can invent a route can also invent one that does not exist. A hallucinated path enters the document as if it were real, and every mock, scenario, and review built on that spec inherits the false route. The risk is not a small typo but a fabricated contract that reads as fact.
Keeping route creation deterministic prevents that. The structure comes from code that is actually resolved, and the model never gets a hand in deciding which paths exist.
The split between extraction and AI fill
| Step | Who does it | What it can produce |
|---|---|---|
| Route extraction | Deterministic scan | Proven routes, methods, and paths |
| Completeness gate | Deterministic scan | Proven, proven-empty, and gap labels |
| Gap fill | AI, on request | Bounded slices for specific gap codes |
| Route invention | No one | Never produced |
The model works downstream of the gate, on unknowns the scan has already named, rather than upstream where it could shape the route list.
What a gap fill looks like
A gap is a specific element on a specific handler, such as a response field the scan could not resolve. The AI fill is deliberately small and pointed.
- The gate names the gap with a code and a handler.
- The AI returns a bounded slice for that element.
- The fill stays attached to the named gap rather than expanding into new routes.
- You review the fill against the source before adopting it.
Because the fill is tied to a gap code, it cannot quietly grow into a new method or path. A model-only note remains a hypothesis until it is checked, and it does not reclassify the deterministic structure.
Say the scan proves a POST route and its request body but cannot resolve the shape of the error response. The gate marks that one response as a gap. The model can propose a bounded error schema for that response, drawn from the handler's error branches, and it stays attached to the existing POST. It cannot add a second path or a DELETE method while it works, and if the proposed schema does not match the handler's actual branches, the review rejects it. The route count before and after the fill stays identical.
Why this boundary makes the spec trustworthy
The boundary keeps the two things the model is good and bad at separate. The model can reason about a concrete unknown faster than a person, but it cannot be trusted to enumerate the surface. Letting it fill gaps uses the strength without exposing the route list to hallucination.
Source code is not sent anywhere by default, and a model key is not required for the static scan. A successful scan still does not prove the implementation conforms, and the AI fill does not turn an unresolved route into a confirmed one without review.
Powerduck enforces the lane in the tooling: deterministic extraction proves the routes, and AI only fills the gaps the gate names.
Frequently asked questions
Can AI add a new endpoint during a scan? No. It can fill a specific gap on a detected route, but it cannot invent a route, method, or path.
What keeps a gap fill from becoming a hallucinated route? The fill is a bounded slice tied to a named gap code and handler, and you review it against the source before adopting it.
Is a model key needed to extract routes? No. The deterministic scan runs without a model key, and source code is not sent anywhere by default.
The bottom line
The model has a deliberately narrow job: fill the explicit gaps the completeness gate names, with bounded slices attached to real handlers. Route creation stays deterministic, so the model cannot invent paths, and model-only notes remain hypotheses until verified. This uses the model's speed on concrete unknowns while keeping the surface area grounded in code. The line between filling a gap and inventing a route is what keeps the whole spec trustworthy. Continue in the code-to-OpenAPI guide.
Top comments (0)