Review Docs

---
argument-hint: "<pr-number>"
description: "Review doc PR for accuracy, test commands, compare patterns"
model: claude-opus-4-5-20251101
allowed-tools: ["Bash", "Read", "Glob", "Grep", "Edit", "Write", "WebSearch", "WebFetch", "AskUserQuestion"]
---

# Review Documentation PR

**If `$ARGUMENTS` is empty or not provided:**

Display usage information:

This command reviews documentation PRs for technical accuracy by testing commands, validating configs, and ensuring consistency with existing patterns.

**Usage:** `/review-docs <pr-number>`

**Example:** `/review-docs 153`

**What it does:**

1. Analyzes PR changes and extracts testable commands/configs
2. Creates a validation plan for your approval
3. Tests commands locally (with Docker containers as needed)
4. Compares against existing docs patterns
5. Generates a review report

Ask the user: "What PR number would you like to review?"

---

**If `$ARGUMENTS` is provided:**

Review documentation PR #$ARGUMENTS collaboratively. This is a guided process - present plans and get approval before executing tests.

## Non-Negotiable Verification Requirements

**These requirements cannot be skipped or waived. Every PR review MUST complete these verifications.**

### 1. Command Verification (MANDATORY)

Every shell command (`bash`, `sh`) in the PR MUST be executed. No exceptions.

- If it can't run locally, it MUST run in Docker
- If it requires real cloud credentials, test equivalent with local emulator (MinIO for S3, fake-gcs-server for GCS, etc.)
- Commands that truly cannot be tested must be explicitly acknowledged by the reviewer

### 2. SQL Command Verification (MANDATORY)

Every SQL statement MUST be run against a real SQLite database:

- Create a test database
- Execute the exact SQL from the documentation
- Verify output matches what the documentation claims
- PRAGMA statements, SELECT queries, schema commands - all must be tested

### 3. Config Verification (MANDATORY)

Every YAML/TOML configuration MUST be validated:

- **Syntax validation**: Parse without errors (use `yq`, `python3 -c "import yaml"`, etc.)
- **Litestream validation**: Run with `litestream replicate -config <file>` to verify it's accepted
- **Environment variable placeholders**: Check format is correct (`${VAR}` or `$VAR`)

### 4. Environment Variable Verification (MANDATORY)

Every environment variable referenced MUST be checked:

- Verify the naming follows existing conventions (check `content/` for patterns)
- Verify it's documented or has a cross-reference
- Test with actual values where possible

### 5. Evidence Requirement (MANDATORY)

The final report MUST include proof of every verification:

- **Full command output** (not paraphrased) in collapsible sections
- **SQL query results** with exact output
- **Config validation output** showing success/failure
- **Any errors encountered** and how they were resolved

### 6. Go Version Verification (MANDATORY)

If the PR mentions a minimum Go version requirement (e.g., "Go 1.21 or later"), verify it matches the litestream `go.mod`:

```bash
# Try local repo first, fall back to GitHub API
if [ -f ../litestream/go.mod ]; then
  grep "^go " ../litestream/go.mod
else
  gh api repos/benbjohnson/litestream/contents/go.mod --jq '.content' | base64 -d | grep "^go "
fi

• The documented version MUST match or be compatible with go.mod
• If go.mod says go 1.24.1, documentation should say "Go 1.24 or later"
• Flag any mismatch as a blocking issue

7. Temporary Directory Requirement (MANDATORY)

ALL test artifacts MUST be created in /tmp/litestream-review/ - NEVER in source repositories.

• Test databases: /tmp/litestream-review/test.db
• Config files: /tmp/litestream-review/litestream.yml
• Test scripts: /tmp/litestream-review/test.sh
• Build artifacts: /tmp/litestream-review/dist/
• Any generated files: /tmp/litestream-review/

Setup at start of review:

rm -rf /tmp/litestream-review && mkdir -p /tmp/litestream-review
cd /tmp/litestream-review

Cleanup at end of review:

rm -rf /tmp/litestream-review

NEVER create files in:

• ../litestream/ (the Litestream source repo)
• The current documentation repo (except for actual doc edits)
• Any other source repository
• User's home directory

HARD BLOCK: You cannot generate a final report until ALL verifications are complete OR the reviewer has explicitly acknowledged each item that cannot be verified.

---

Litestream Binary Location

The Litestream source code MAY be available at ../litestream (relative). This is optional - not all contributors will have the repo cloned locally.

If local repo is not available:

• Use gh api to fetch files from GitHub (e.g., go.mod for version checks)
• Use the installed litestream binary for command testing
• Skip tests that require building from source (acknowledge in report)

If testing requires a specific branch or unreleased feature:

1. Check if the docs PR references a Litestream PR (e.g., "Documents feature from litestream#862")

2. Fetch and checkout that branch in the Litestream repo:

   cd ../litestream
   gh pr checkout <litestream-pr-number>
   

3. Build the binary:

   cd ../litestream
   go build -o litestream ./cmd/litestream
   

4. Use the local binary for testing:

   ../litestream/litestream version
   ../litestream/litestream replicate ...
   

5. After testing, return to main:

   cd ../litestream
   git checkout main
   

0. Check PR Rebase Status

This MUST be the first check before any other review steps.

Check if the PR needs a rebase:

gh pr view $ARGUMENTS --json mergeStateStatus,mergeable,baseRefName,headRefName,title

Evaluate the results:

• mergeable: MERGEABLE - PR can be merged cleanly, proceed with review
• mergeable: CONFLICTING - PR has merge conflicts, needs rebase
• mergeStateStatus: BEHIND - PR is behind base branch, may ne