Docs Sync

Docs Sync

Overview

Identify doc coverage gaps and inaccuracies by comparing main branch features and configuration options against the current docs structure, then propose targeted improvements.

Workflow

1. Confirm scope and base branch

• Identify the current branch and default branch (usually main).
• Prefer analyzing the current branch to keep work aligned with in-flight changes.
• If the current branch is not main, analyze only the diff vs main to scope doc updates.
• Avoid switching branches if it would disrupt local changes; use git show main:<path> or git worktree add when needed.

2. Build a feature inventory from the selected scope

• If on main: inventory the full surface area and review docs comprehensively.
• If not on main: inventory only changes vs main (feature additions/changes/removals).
• Focus on user-facing behavior: public exports, configuration options, environment variables, CLI commands, default values, and documented runtime behaviors.
• Capture evidence for each item (file path + symbol/setting).
• Use targeted search to find option types and feature flags (for example: rg "Settings", rg "Config", rg "os.environ", rg "OPENAI_").
• When the topic involves OpenAI platform features, invoke $openai-knowledge to pull current details from the OpenAI Developer Docs MCP server instead of guessing, while treating the SDK source code as the source of truth when discrepancies appear.

3. Doc-first pass: review existing pages

• Walk each relevant page under docs/ (excluding docs/ja, docs/ko, and docs/zh).
• Identify missing mentions of important, supported options (opt-in flags, env vars), customization points, or new features from src/agents/ and examples/.
• Propose additions where users would reasonably expect to find them on that page.

4. Code-first pass: map features to docs

• Review the current docs information architecture under docs/ and mkdocs.yml.
• Determine the best page/section for each feature based on existing patterns and the API reference structure under docs/ref.
• Identify features that lack any doc page or have a page but no corresponding content.
• Note when a structural adjustment would improve discoverability.
• When improving docs/ref/* pages, treat the corresponding docstrings/comments in src/ as the source of truth. Prefer updating those code comments so regenerated reference docs stay correct, instead of hand-editing the generated pages.

5. Detect gaps and inaccuracies

• Missing: features/configs present in main but absent in docs.
• Incorrect/outdated: names, defaults, or behaviors that diverge from main.
• Structural issues (optional): pages overloaded, missing overviews, or mis-grouped topics.

6. Produce a Docs Sync Report and ask for approval

• Provide a clear report with evidence, suggested doc locations, and proposed edits.
• Ask the user whether to proceed with doc updates.

7. If approved, apply changes (English only)

• Edit only English docs in docs/**.
• Do not edit docs/ja, docs/ko, or docs/zh.
• Keep changes aligned with the existing docs style and navigation.
• Update mkdocs.yml when adding or renaming pages.
• Build docs with make build-docs after edits to verify the docs site still builds.

Output format

Use this template when reporting findings:

Docs Sync Report

• Doc-first findings
• Page + missing content -> evidence + suggested insertion point
• Code-first gaps
• Feature + evidence -> suggested doc page/section (or missing page)
• Incorrect or outdated docs
• Doc file + issue + correct info + evidence
• Structural suggestions (optional)
• Proposed change + rationale
• Proposed edits
• Doc file -> concise change summary
• Questions for the user

References

• references/doc-coverage-checklist.md

Doc Coverage Checklist

Use this checklist to scan the selected scope (main = comprehensive, or current-branch diff) and validate documentation coverage.

Feature inventory targets

• Public exports: classes, functions, types, and module entry points.
• Configuration options: *Settings types, default config objects, and builder patterns.
• Environment variables or runtime flags.
• CLI commands, scripts, and example entry points that define supported usage.
• User-facing behaviors: retry, timeouts, streaming, errors, logging, telemetry, and data handling.
• Deprecations, removals, or renamed settings.

Doc-first pass (page-by-page)

• Review each relevant English page (excluding docs/ja, docs/ko, and docs/zh).
• Look for missing opt-in flags, env vars, or customization options that the page implies.
• Add new features that belong on that page based on user intent and navigation.

Code-first pass (feature inventory)

• Map features to the closest existing page based on the docs navigation in mkdocs.yml.
• Prefer updating existing pages over creating new ones unless the topic is clearly new.
• Use conceptual pages for cross-cutting concerns (auth, errors, streaming, tracing, tools).
• Keep quick-start flows minimal; move advanced details into deeper pages.

Evidence capture

• Record the main-branch file path and symbol/setting name.
• Note defaults or behavior-critical details for accuracy checks.
• Avoid large code dumps; a short identifier is enough.

Red flags for outdated or incorrect docs

• Option names/types no longer exist or differ from code.
• Default values or allowed ranges do not match implementation.
• Features removed in code but still documented.
• New behaviors introduced without corresponding docs updates.

When to propose structural changes

• A page mixes unrelated audiences (quick-start + deep reference) without clear separation.
• Multiple pages duplicate the same concept without cross-links.
• New feature areas have no obvious home in the nav structure.

Diff mode guidance (current branch vs main)

• Focus only on changed behavior: new exports/options, modified defaults, removed features, or renamed settings.
• Use git diff main...HEAD (or equivalent) to constrain analysis.
• Document removals explicitly so docs can be pruned if needed.

Patch guidance

• Keep edits scoped and aligned with existing tone and format.
• Update cross-links when moving or renaming sections.
• Leave translated docs untouched; English-only updates.