docs-editor

OpenAI Cookbook docs editor

Objective

Review Cookbook content conservatively. Improve correctness and readability without changing the author's intent, inventing facts, or creating unrelated churn.

Workflow

1. Define the scope

• Prefer explicit paths or the files changed in the pull request.
• For pull requests, review changed .md and .mdx files plus Markdown cells in changed .ipynb files.
• Review registry.yaml and authors.yaml when content is added, moved, removed, or attributed to a new author.
• Stay within the requested content. Do not turn a focused review into a repository-wide rewrite.

2. Protect notebook integrity

• When the request is editorial, edit only notebook Markdown cells.
• Preserve code cells, outputs, execution counts, attachments, cell order, cell IDs, and notebook and cell metadata.
• Avoid reserializing an entire notebook for a small prose change. Inspect the diff for unintended JSON churn.
• Do not execute notebook code unless the user requests it or code changes are in scope. Markdown-only edits require structural validation, not calls to external services.
• Never add hard-coded secrets. Document required environment variables such as OPENAI_API_KEY.

3. Review the content

Load resources/style-guide.md and check:

• Technical claims, API names, model names, identifiers, commands, paths, and URLs.
• Agreement between prose, code, sample inputs, and expected outputs.
• Prerequisites, dependencies, environment variables, and steps needed to run an example.
• File and notebook names, headings, lists, numbering, cross-references, and links.
• Grammar, spelling, punctuation, terminology, capitalization, and concise wording.
• Publication metadata in registry.yaml and author metadata in authors.yaml when applicable.

Verify uncertain technical claims from an authoritative source or flag them for review. Do not guess.

4. Prioritize findings

Use the repository's review bar:

• P0: Broken notebook JSON; hard-coded secrets; materially false or unsafe guidance; or any repository-defined P0 issue, including naming violations, typos, broken links, inconsistent formatting, placeholder identifiers, undocumented environment variables, or out-of-sync publication metadata.
• P1: Misleading instructions, prose that contradicts code or output, missing prerequisites, or a required link that does not work.
• P2: Clear improvements to grammar, consistency, organization, or readability that do not affect correctness.
• P3: Optional polish with little effect on comprehension.

5. Make safe edits

• Fix obvious typos, grammar, punctuation, broken local references, and clear prose/code mismatches.
• Keep changes minimal, local, and reversible.
• Preserve exact literals, code identifiers, commands, values, counts, conditions, modality, negation, and uncertainty markers.
• Tighten prose only when meaning stays unchanged. Prefer concrete nouns, strong verbs, short introductions, and direct instructions.
• Flag any change that depends on product knowledge or could alter meaning instead of guessing.
• Do not make file-wide formatting or stylistic changes solely for uniformity.

6. Validate the result

For any changed notebook, run the repository validator:

env -u VIRTUAL_ENV uv run --with nbformat python .github/scripts/check_notebooks.py

Then:

• Run git diff --check.
• Inspect the diff and confirm that notebook changes are limited to intended Markdown cells.
• Run an available YAML linter if registry.yaml or authors.yaml changed.
• Run the relevant example or test only when executable content changed and its dependencies are available.

7. Report the review

Provide:

• A short summary of the scope and edits.
• Auto-fixed items.
• Remaining findings grouped by priority with file and cell or line references.
• The validation commands run and their results.

If no issues remain, say so explicitly.