Merge pull request #122 from USACE-RMC/docs/dev/reviewer-workflow-rewrite

Rework Reviewer Workflow as a screenshot-driven walkthrough

Author: AdamGohs

.gitignore

@@ -46,6 +46,7 @@ src/data/
 .claude/mcp.json
 .mcp.json
 .playwright-mcp/
+.playwright-auth/
 
 # Skill review output (screenshots ignored, reports tracked)
 review-output/

docs/dev/documentation-guide/11-author-workflow.mdx

@@ -56,6 +56,8 @@ Within a minute or two of opening the PR, three bot comments appear:
 2. A stage progression comment identifying the lane and what review is needed next
 3. A hidden state comment that renders as an "Assigned reviewers for this PR" block, tracking which individuals the site administrator has assigned to each review stage
 
+For the reviewer's view of these same three bot comments — and the rest of the page a reviewer lands on — see [Reviewer Workflow](./12-reviewer-workflow.mdx).
+
 ## Responding to review comments
 
 Reviewers post comments on specific lines in the Files changed tab. For each comment, the author makes the fix, pushes a commit, and replies explaining what was done. The reviewer resolves the thread when satisfied.
@@ -64,6 +66,8 @@ For suggested changes (pre-filled code blocks), the author can click **Commit su
 
 **All comment threads must be resolved before the PR can merge.**
 
+Authors writing clear, descriptive commit messages make a reviewer's life much easier — see [Reviewer Workflow §3 — Navigating commits within a PR](./12-reviewer-workflow.mdx#navigating-commits-within-a-pr) for how a reviewer uses your commit messages to focus their attention.
+
 ## The technical edit (Lanes 1, 2, and 3)
 
 After the previous review stage approves the PR, the technical edit stage begins. A team member triggers an AI-assisted technical edit against the PR. The AI reads the source MDX files directly and posts inline review comments covering grammar, tense, clarity, terminology, and Section 508 accessibility. The document is not yet deployed to the live site at this stage — the technical edit works on source files, so the live deploy is deferred until the technical edit is complete.

docs/dev/documentation-guide/12-reviewer-workflow.mdx

@@ -37,6 +37,8 @@ Reviewers are assigned ad-hoc per PR via the Reviewers sidebar (gear icon → ty
 
 For Lane 1, the site administrator assigns up to three people across the lifecycle: the peer reviewer (if the author did not), the Lead Civil after peer approval, and the Director after the technical edit.
 
+For what the assigned reviewer experiences from the email notification through submitting their review, see [Reviewer Workflow](./12-reviewer-workflow.mdx). This is especially useful context when onboarding a first-time reviewer.
+
 **Per-individual gating.** When the site administrator assigns someone via the Reviewers sidebar, the stage progression workflow records that person in a hidden state comment on the PR, keyed by the current review stage. Only approvals from those assigned reviewers advance the stage — drive-by approvals from other team members are logged but ignored by the workflow. Multiple people can be assigned at the same stage; the first approval from any of them advances the PR.
 
 To replace an assigned reviewer, the site administrator removes them from the Reviewers sidebar and adds the correct person. The state comment updates automatically.