Workflows

Review the diff from the last merged PR in `your-org/your-product`. Identify any new features, APIs, or other changes that require documentation.

For each new addition, draft documentation updates that explain what it does, when to use it, and how to configure it. Include a code example where relevant.

Success criteria: After reading any new or updated documentation, users understand what the feature is, if it applies to tasks they do, and how to use it.

## Important

- Only document changes that affect end users. Skip internal refactors or dependency updates.
- Match the style and structure of existing docs pages.

Review all MDX files changed in the last merged PR against the style guide at `path/to/style-guide`.

Open a pull request to resolve any style violations that can be fixed automatically. For any edits that require judgment or nuance, note them in the PR body with the specific lines, rule violations, and suggested fixes.

Success criteria:
- All style violations have a proposed resolution.
- No new style violations are introduced.

## Important

- Do not change content meaning. Only correct style violations.
- Skip any files in language subdirectories (`es/`, `fr/`, `zh/`).

Review the diff from the last merged PR in `your-org/your-product` for changes to API endpoints, parameters, response shapes, or error codes.

Update the corresponding API specifications or pages in the docs to reflect the changes. Include updated parameter descriptions, type information, and examples where affected.

Success criteria: All API specifications and pages are up to date with the changes in the product repository.

## Important

- If a parameter or endpoint was removed, mark it as deprecated rather than deleting it unless the code explicitly removes it with no deprecation period.
- If no API changes were introduced, do nothing.

Compare the English MDX files in the repo against their counterparts in the `es/`, `fr/`, and `zh/` subdirectories. Use git history to identify English files updated more recently than their translations.

Open a pull request that lists pages that are out of sync, organized by language. For each page, include the date of the last English update and a brief summary of what changed so translators have context on what to update.

Success criteria: Any discrepancies between the English and translated files are identified and listed in the pull request.

## Important

- If a translated file does not exist, flag it as missing rather than out of sync.
- Group findings by language, then by how far out of date they are (most stale first).

Audit all MDX files in the docs for SEO and metadata quality. Check for:

- Missing or empty `title` frontmatter
- Titles that are too long (over 60 characters) — long titles are truncated in search result snippets
- Titles that follow a boilerplate pattern like "PageType - Name" without describing the specific content of the page
- Missing or empty `description` frontmatter (see OpenAPI pages below — do not treat as missing when an OpenAPI spec supplies the description)
- Descriptions that are too short (under 130 characters) — short descriptions are frequently ignored by Google in favor of auto-generated snippets
- Descriptions that are too long (over 160 characters)
- Pages that share an identical description with other pages — each page needs a unique description

Open a pull request with improvements for any issues found.

When writing titles: be descriptive and specific about what the page covers. Avoid generic patterns like "Overview - Product Name". Target 50-60 characters.

When writing descriptions: summarize what the specific page covers in plain language. Include 2-3 terms a user would actually search for. Never reuse the same description across pages. Target 130-155 characters.

### Pages with `openapi:` in frontmatter (API reference from spec)

The `openapi:` frontmatter value can be either an **operation reference** (e.g., `openapi: GET /users/{id}`) or a **file reference** (e.g., `openapi: ./openapi.yaml`). Only operation references supply per-page `summary` and `description` from the spec.

For pages with an **operation reference**:
- Read the referenced OpenAPI spec file to check whether the operation defines a `description`.
- If the operation **has** a `description`: do not add a `description:` field to frontmatter. If one was incorrectly added, remove it so the metadata comes from the spec.
- If the operation **has no** `description`: audit `description` frontmatter as normal — add one if missing or fix it if it fails the quality checks.
- If the operation defines a `summary` and the page has no `title:` frontmatter, treat the title as present — do not add one.
- Never edit the OpenAPI spec files themselves.

For pages with a **file reference**, audit all frontmatter fields as normal.

Success criteria:
- Pages have a unique title under 60 characters that describes the specific content
- Pages have a unique description between 130 and 160 characters (except for pages where the OpenAPI spec supplies the description)

## Important

- Only update frontmatter. Do not change page content or OpenAPI spec files.
- If all pages have complete and reasonable metadata, do nothing.

Review all merged PRs in `your-org/your-product` from the past week. Draft a changelog entry summarizing new features, bug fixes, and breaking changes.

Success criteria: The changelog accurately reflects the week's changes and is ready for review.