Docs Workflow
Documentsdocs-workflowDocs Workflow is an Agent Skill for documents published in the grafana/tempo repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/grafana/tempo/blob/HEAD/.claude/skills/docs-workflow/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/docs-workflow, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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
- Load local context per
../shared/load-context.md. The sub-skills inherit this context. - 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-reviewin 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)