docs-workflow

name	docs-workflow
description	End-to-end workflow for PR documentation — check, write, review, and optionally validate screenshots. Use when the user wants to document one or more PRs from start to finish, run the full docs pipeline, or asks for a complete documentation pass on PRs.
metadata	{"use_case":"write-or-update, quality-review","workflow":"create, evaluate"}

PR documentation workflow

A three-step pipeline for documenting PR changes: assess gaps, write docs, review quality. Each step uses an existing skill; this workflow ties them together.

Before you begin

1. Load local context per ../shared/load-context.md. The sub-skills inherit this context.
2. Get one or more PR numbers and target branch context from the user.

Steps

1. Check — identify documentation gaps

Run ../docs-pr-check/SKILL.md.

Input: PR list from user. Output: Classification table and prioritized gap summary.

Present the table to the user. Confirm which PRs to proceed with before moving to step 2.

2. Write — create or update documentation

Run ../docs-pr-write/SKILL.md.

Input: PRs classified as "docs needed" or "docs update needed" from step 1, plus gap notes and suggested target files. Output: Updated doc files, PR-to-doc mapping, and open items.

Present the list of changed files and a summary of what was written. Wait for the user to confirm before proceeding to step 3. Do not continue automatically.

3. Review — quality check the new content

Run ../docs-review/SKILL.md on the files changed in step 2.

Input: File paths from step 2, plus any uncertain claims flagged during writing. Output: Review report covering style guide compliance, frontmatter, links, and accuracy.

Present findings. If docs-review flags a real (non-example) secret in its sensitive-data scan, stop here: do not offer to create a PR until the user has rotated or invalidated the value at the source, since it may already persist in git history.

After addressing review feedback, ask: "Would you like me to create a PR, or would you prefer to review the changes locally first?"

Optional: Screenshot validation

If step 1 produced a Screenshot inventory (PRs with UI changes affecting pages that have screenshots), offer to validate them. If yes, run screenshot-check (if available), passing the inventory table from step 1 directly. The user must provide a live URL.

Handoff contract

From	To	What passes	Receiving step validates
Step 1 → Step 2	PR number, classification, gap notes, suggested target files	PR is still accessible (gh pr view succeeds); classification is one of the four valid categories
Step 2 → Step 3	Changed file paths, open items or uncertain claims	Each file path exists on disk; files are non-empty
Step 1 → Screenshot check	Screenshot inventory: PR numbers, affected doc pages, screenshot count, image references	Doc pages exist; image references resolve

Each receiving step must verify its inputs before proceeding. If validation fails (PR deleted, file missing, path changed), stop and report the issue rather than operating on stale data.

When to use this vs. individual skills

Task	Use
One or more PRs need docs end-to-end	This workflow
Just need to check if PRs have docs	docs-pr-check standalone
Already know what to write, have PR numbers	docs-pr-write standalone
Review existing doc changes	docs-review standalone
New docs from scratch, not tied to PRs	docs-from-code (if available)

Known limitations

• Same-agent review. Steps 2 and 3 run in the same agent session. The review step (docs-review) evaluates content that the same agent wrote in step 2. This is structurally self-review and should not be treated as an independent quality gate.
• Human PR review is the independent gate. The mandatory independent verification happens when a human reviews and merges the PR on the target repository — not during step 3 of this workflow.
• High-impact changes warrant separate review. For breaking changes, security-relevant documentation, or migration guides, consider running docs-review in a separate agent session or asking a different team member to review the output before creating a PR.

Reference

• Repo orientation: ../shared/docs-context-guide.md
• Style guide: ../shared/style-guide.md
• Verification checklist: ../shared/verification-checklist.md
• Screenshot validation: screenshot-check (if available)