docs-review

name	docs-review
description	Create or review scenario README files in alloy-scenarios from existing Docker Compose, Helm, and config.alloy files. Use when drafting a new scenario README, rewriting an existing README, checking Writers Toolkit style, or verifying README accuracy against scenario configs and Grafana Alloy documentation.

Scenario README create and review

Create or update a single scenario README.md in alloy-scenarios. This repository documents scenarios only through per-directory README files.

Do not create other documentation pages. Do not edit scenario configuration files. Do not commit, push, or open pull requests unless the user explicitly asks.

Before you begin

Read these shared files in order:

1. ../shared/repo-context.md
2. ../shared/style-guide.md
3. ../shared/best-practices.md

Then read every configuration file in the target scenario directory. See Config-first workflow in ../shared/best-practices.md for the file list by deployment type.

Ask the user for the scenario directory path if it is not clear from context.

Step 1: Choose create or review

Condition	Path
README.md is missing, or is 0 bytes	Create
README.md exists but every ## heading is either absent or contains only placeholder text (for example a bracketed note, a single TODO line, or no body text)	Create
README.md already exists with scenario content	Review

If you're unsure which row applies, treat it as Review. The preservation rules in review mode won't damage a file that turns out to be thin, but the Create path skips preservation checks entirely and can destroy real content if misapplied.

Create and review use the same style, structure, and verification rules.

Step 2: Create a new README

1. Read the closest baseline README listed in ../shared/repo-context.md.
2. Draft README.md using the template in ../shared/style-guide.md.
3. Derive every command, port, URL, component name, and query from the scenario config files.
4. Omit optional template sections that do not apply.
5. Follow ../shared/technical-verification.md.
6. Verify Alloy component claims with ../shared/alloy-verification.md.
7. Check the draft against ../shared/generated-content-review.md.
8. Run through ../shared/verification-checklist.md.
9. Present the draft README to the user. Do not commit.

Step 3: Review an existing README

1. Read the current README.md alongside the scenario config files.

2. Load the previous version for preservation checks:

   git show HEAD:<scenario-dir>/README.md
   

   If the file is new on this branch, compare against the merge base or ask the user which version to preserve against.

3. Classify the change:

   • Style/editorial — the edit touches only wording, grammar, heading text, or paragraph structure, and every command, port, component name, query, credential, and URL in the README is byte-for-byte unchanged from the current file
   • Technical — anything else, including edits that touch a heading immediately above a code block, reorder steps, or change which sections exist

   Default to technical. Only classify as style/editorial if you can point to the specific lines changed and confirm none of them fall in the technical list above.

4. Follow ../shared/technical-verification.md.

5. Verify Alloy component claims with ../shared/alloy-verification.md.

6. Apply ../shared/style-guide.md and ../shared/best-practices.md.

7. Confirm every command, query, credential, env var, and demo manifest from the original README is still present unless the configs changed.

8. Check the draft against ../shared/generated-content-review.md.

9. Run through ../shared/verification-checklist.md.

10. Apply fixes to README.md only. Present results to the user. Do not commit.

Style and format requirements

Apply every rule in ../shared/style-guide.md. In particular:

• Active voice, second person, present tense, contractions
• Sentence case for headings and emphasis used as subheadings
• No gerunds in headings
• No parentheses or brackets in prose
• "Refer to" not "see"
• "Check" not "confirm" in troubleshoot steps
• Every fenced code block must have a language tag

Remove AI-tell phrasing listed in ../shared/generated-content-review.md.

Technical verification

Scenario config files outrank the README when they disagree. Fix the README to match the configs. Flag a config for the contributor instead of changing it if configs disagree with each other, reference something missing from the scenario directory, or contradict the Alloy component reference.

For Alloy component names, arguments, and behavior, verify against the latest reference:

https://grafana.com/docs/alloy/latest/reference/components/

Follow ../shared/technical-verification.md for the full workflow.

Handoff

Present a summary that includes:

1. Task — create or review
2. Scenario directory
3. Changes made — or the full draft for create
4. Style-guide violations found and fixed
5. Likely AI-origin content issues found, using the categories in ../shared/generated-content-review.md
6. Technical verification — claims checked against configs and Alloy docs, with any divergences
7. Preservation — on review, any content from the original README that was kept, restored, or intentionally dropped
8. Open questions — config problems or claims you could not verify
9. Checklist — note any items from ../shared/verification-checklist.md the user should confirm before submitting

Reference

File	Purpose
../shared/repo-context.md	Repository layout and baseline READMEs
../shared/style-guide.md	Style rules and README template
../shared/best-practices.md	Config-first workflow and pitfalls
../shared/generated-content-review.md	Detailed AI-tell patterns and reporting categories, beyond the basics in best-practices.md
../shared/technical-verification.md	Technical review steps
../shared/alloy-verification.md	Alloy docs cross-check
../shared/verification-checklist.md	Pre-submit checklist