## TL;DR
Track visited references and stop resolving when you see a cycle. The agent's parser followed schema references depth-first with no memory, so A to B to A looped forever and the docs job hung or crashed.
Fix: keep a set of in-progress references, emit a named reference instead of expanding on revisit, and use a resolver library that handles recursion.

## The error
```text
agent's openapi parser failed on recursive schemas
```

## Steps
1. Confirm the cycle: search the spec for the schemas named in the hang or stack trace and trace the reference chain until a schema references one already on the path.
   Expected: you find the A to B to A (or longer) cycle.
2. Check the parser code for reference resolution: if it recurses with no visited-set, that is the bug.
   Expected: you locate the resolve function with no cycle guard.
3. Add cycle detection: maintain a set of references currently being expanded; when a reference is already in the set, emit a link to the already-documented schema instead of expanding it again.
   Expected: resolution terminates; recursive schemas render once with cross-links.
4. Alternatively, switch to a resolver library that handles recursion natively and configure it to preserve references rather than fully dereferencing.
   Expected: the spec loads without hangs and recursive models are documented.
5. Re-run doc generation with a timeout guard so any future cycle fails fast instead of hanging the pipeline.
   Expected: docs build completes; recursive schemas show as linked model entries.

## Use this when
- doc generation hangs or stack-overflows on an OpenAPI spec
- the spec contains schemas that reference each other in a cycle
- the parser was hand-rolled without cycle detection

## Not for this skill when
- references fail because the target is missing (an unresolvable reference, not a cycle)
- the spec is valid but huge (a performance issue, not recursion)
- the cycle is in example payloads rather than schema definitions

## Variant phrasings
- openapi parser infinite loop on circular schema refs
- docs agent stack overflow resolving recursive models
- cyclic schema references crash doc generation
- parser hangs on mutually referencing components

## Why it happens
Reference resolution is naturally recursive, and a cycle in the schema graph makes naive recursion infinite. Real-world specs use recursion constantly (trees, linked lists, nested comments), so any resolver without a visited-set will eventually meet a cycle.

## Edge cases
- Self-referencing schemas (a node with a child of its own type): the simplest cycle; the guard must catch depth-1 cycles too.
- Cycles through composition keywords (allOf, oneOf): track references across combinators, not just direct properties.
- Rendering: show recursive fields as links to the model definition with a "recursive" note rather than expanding inline.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_NJo9ChY1B6RT-a_pB5oWMg