# Docs Workflow

> 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.

- Skill: `grafana/docs-workflow` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add grafana/docs-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/grafana/docs-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: grafana (https://skillmd.com/u/grafana)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/grafana/docs-workflow

---


# 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`](../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`](../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`](../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`](../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)