[kabraham13]

Problem

The "Docs Pipeline" workflow fails on every push to main that touches api-reference/openapi.yaml. It failed on each of the last 8 runs, back to 2026-09-29, most recently on #478 (Run the docs pipeline step, exit code 1).

The log shows:

[11/11] Generating: thin_page for unknown...
  Error: [Errno 21] Is a directory: '.../docs/resources/breaking-changes-change-notices'
Done. Generated: 2, Errors: 1
No .mdx files found in pipeline/drafts/<run>
EVALUATE FAILED - drafts have errors.

Cause

detect_gaps.py takes page IDs from docs.json, which have no extension (docs/resources/foo), and puts them in the path of thin_page, missing_description and apiref_narrative_page gaps. The later steps treat path as a file:

• generate.py reads REPO_ROOT / path. For a page ID that is not a file, load_file swallows FileNotFoundError and returns an empty string, so the model is asked to expand a page it was never shown. When a folder has the same name as the page (breaking-changes-change-notices.mdx and breaking-changes-change-notices/), the read raises IsADirectoryError and the run crashes.
• The draft is named from the same path (docs--getting-started--supported-languages, no .mdx), so evaluate.py, which globs *.mdx, finds no drafts and fails the run.

evaluate.py and test_open_prs.py already assume extension-bearing paths (docs--admin--overview.mdx, docs/a.mdx).

Measured on current main: all 7 gaps that carry a path pointed at something that is not a file (5 with no extension, 2 that resolve to a directory).

Change

• pipeline/util.py: add page_file(page_id), which returns the repo-relative .mdx or .md file for a page ID, or None.
• pipeline/detect_gaps.py: use it where the three gap types are emitted. Detection is unchanged: the same 13 gaps, with only the path values differing.
• pipeline/test_page_file.py: 6 stdlib tests, including a page next to a same-named folder and a folder with no page.

Verification

• python -m unittest discover -s pipeline -p "test_*.py" passes (30 tests: 24 existing, 6 new), without yaml installed, as in CI.
• Detector output on main before and after: 13 gaps both times, everything except path identical, and 0 of 7 paths are non-files after (7 of 7 before).
• With the model client stubbed, generate.py now names the three thin_page drafts docs--...--<page>.mdx and load_file reads the real page content for each.

Not verified: a full pipeline run, which needs the model API and the later steps (review, promote, ship).

Heads up

Once this merges, the next change to openapi.yaml lets the pipeline get past generate and evaluate for the first time in these runs. It will call the model to expand the three thin pages (supported-languages, google-sheets, breaking-changes-change-notices) and may open a PR with the result. Use the manual workflow_dispatch with dry_run to see what it would do before relying on it.

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
deepl-c950b784	🟢 Ready	View Preview	Oct 28, 2026, 6:10 PM

💡 Tip: Enable Automations to automatically generate PRs for you.