diff --git a/.gitignore b/.gitignore index 153add925..c46827399 100644 --- a/.gitignore +++ b/.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/ diff --git a/docs/dev/documentation-guide/11-author-workflow.mdx b/docs/dev/documentation-guide/11-author-workflow.mdx index 3a0ad3537..1f3272776 100644 --- a/docs/dev/documentation-guide/11-author-workflow.mdx +++ b/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. diff --git a/docs/dev/documentation-guide/12-reviewer-workflow.mdx b/docs/dev/documentation-guide/12-reviewer-workflow.mdx index 2b624567e..0eb9bec93 100644 --- a/docs/dev/documentation-guide/12-reviewer-workflow.mdx +++ b/docs/dev/documentation-guide/12-reviewer-workflow.mdx @@ -2,6 +2,7 @@ title: Reviewer Workflow --- +import FigureNoRef from '@site/src/components/FigureNoRef'; import NavContainer from '@site/src/components/NavContainer'; import ProcessList from '@site/src/components/ProcessList'; import TableVerticalNoRef from '@site/src/components/TableVerticalNoRef'; @@ -12,78 +13,486 @@ import TableVerticalNoRef from '@site/src/components/TableVerticalNoRef'; What peer reviewers and RMC Lead Civils do when assigned to review a documentation pull request. Everything in this workflow happens through the GitHub web interface — no local tooling is required. -## Prerequisites +--- + +## Completing a review step by step + +Click any step below to jump to the matching section. + + + Before you start — why we work this way + + Go to step + + + ), + }, + { + title: ( + + Getting the review request + + Go to step + + + ), + }, + { + title: ( + + The PR page — a guided tour + + Go to step + + + ), + }, + { + title: ( + + Reading the document on the preview site + + Go to step + + + ), + }, + { + title: ( + + Leaving your first comment + + Go to step + + + ), + }, + { + title: ( + + Submitting your review + + Go to step + + + ), + }, + { + title: ( + + The backcheck round + + Go to step + + + ), + }, + { + title: ( + + You're done + + Go to step + + + ), + }, + ]} +/> + +### 1. Before you start — why we work this way + +Reviewing documentation on GitHub is unfamiliar territory for most engineers. Before clicking anything, this short tour explains the four concepts everything else in this chapter is built on: the **repository**, **branches**, **commits**, and **pull requests**. Read this once and most of the rest of the chapter will feel obvious. + +#### The site you're reviewing is built from text files in a repository -A reviewer needs a GitHub account and membership in the `usace-rmc` organization. A site administrator sends the invitation by email; the reviewer clicks the link to accept. +Every page on the RMC Software Documentation site is generated from a text file. All of those files live together in a single folder we call the **repository** — `RMC-Software-Documentation`. +The repository is the source of truth: change a file there, the site updates. You will not be editing any of these files. Your job is to read the rendered output and either approve it or leave +comments. The author is the one who edits. -## Receiving a review request +#### A branch is a parallel copy of the repository -GitHub emails the reviewer with the subject "You were requested to review [title]." The link in the email opens the PR. +If an author edited the live files directly, every keystroke would be on the published site instantly — typos and all. Instead, the author creates a **branch**: a working copy of the entire repository that they can edit freely without affecting anything readers see. -## Where to read the document +The main branch — literally called `main` — is the published site. Branches with names like `docs/minor/totalrisk-users-guide-v1.1` are work-in-progress copies. +The branch sits off to the side. Anything on `main` is live. Anything on a branch is in progress. -Both peer reviewers and Lead Civils review on the preview URL. The PR's comment thread contains a bot comment titled "Preview deployed" with a URL. The link opens the rendered document on an unadvertised preview site with a DRAFT watermark. +#### A commit is a saved snapshot -The reviewer reads the document as they would any web page. The review happens in the rendered preview — reviewers do not edit files. +Authors don't save every keystroke — they save in batches called **commits**. Each commit bundles up a coherent set of changes with a short message describing what was done. Some commits are +small — a small typo fix, a single figure update, a one-paragraph rewording. Others are large — substantial changes to existing content or the addition of a whole new section. The commit message +is the author's chance to explain what's in each batch. For reviews of existing documents that underwent a version change, one of the first commits is often a large scaffolding +commit that copies the previous version's files into a new version folder. The subsequent commit(s) are the ones that actually edit the content. + +#### A pull request is a formal proposal to merge a branch back into main + +When an author is ready for review, they open a **pull request** (PR). A PR is a proposal: "please merge this branch into `main` so it goes live." It holds the review conversation in one place — +comments, approvals, and the eventual merge button. + +Two things matter: + +1. **Pull requests are the only way changes reach the live site.** Direct edits to `main` are blocked. Every change goes through this same review process. +2. **A reviewer's entire job happens inside the pull request.** You will never edit a file directly. You read the rendered preview, leave comments on the PR, and approve when you're happy. + +#### Glossary Repository', + 'Branch', + 'Commit', + 'Pull request (PR)', + 'Merge', + 'Main', ], [ - 'Technical accuracy — claims, equations, procedures, completeness', - 'Technical quality and oversight — alignment with RMC standards, scope appropriateness, defensibility of conclusions', + 'The folder of files that the website is built from.', + 'A parallel copy of the repository where someone is making edits without disturbing the live site.', + 'A saved snapshot of one batch of edits, with a short message describing what changed.', + 'A formal proposal to merge a branch into main. The conversation, the review, and the merge all happen here.', + 'The act of folding a branch’s commits into main, making them part of the live site.', + 'The branch that is the live site. Protected — you can only merge into it through a pull request.', ], ]} + colWidths={['25%', '75%']} +/> + +:::tip Checkpoint +You now know what a repository, branch, commit, and pull request are, and where your role as a reviewer fits in. You haven't clicked anything yet. +::: + +--- + +### 2. Getting the review request + +When the site administrator assigns you to a PR, GitHub sends you an email. The subject begins with the PR title and the sender is `notifications@github.com`. Inside, GitHub names +the person who requested the review, the PR number, and offers a **View it on GitHub** button or link that takes you straight to the PR page. + + + +_The subject line tells you the PR title and number. The **View it on GitHub** button or link is the fastest way to open the PR — click it and you're in._ + +#### If you can't find the email + +Emails get filtered, archived, or buried. If you know you've been asked to review something but can't find the message, you can pull up every PR awaiting your review directly from GitHub. On +github.com, navigate to the `RMC-Software-Documentation` repository, click the **Pull requests** tab, and find the pull request of interest in the list. + + + +:::tip Checkpoint +You can open the PR either from the email or by filtering GitHub's pull-request list to `review-requested:@me`. +::: + +--- + +### 3. The PR page — a guided tour + +Clicking through from the email lands you on the PR's **Conversation** tab. The first time you see this page, it looks like a lot — there's a sidebar, several tabs, status badges, and a stream of comments. Most of it is informational. Only a handful of elements are things you'll actually click. + + + +_(1) The yellow banner confirming you're a requested reviewer. (2) The PR title and its number — use the number when referring to the PR in writing. (3) The four tabs across the top: **Conversation**, **Commits**, **Checks**, **Files changed**. The badges next to each show the count of comments, commits, and changed files. (4) The **Reviewers** sidebar — your username appears here once you're assigned. (5) The **Add your review** button in the top right; once you start leaving comments it changes to **Finish your review**._ + +#### The bot comments — the three automated posts you should recognize + +Three bot comments appear on every PR in this project. Together they give you everything you need without clicking around. + + + +_(1) **Assigned reviewers for this PR.** A table of who needs to approve at the current stage. This is the source of truth for who the bot is waiting on. (2) **Stage progression.** Shows which review lane this PR is in (peer review, lead civil review, technical edit, director review) and what's required to advance. (3) **Preview deployed.** A URL pointing to the rendered version of the document — this is where you do your actual reading, not the Files changed tab. Click that URL to open the preview site._ + +#### Navigating commits within a PR + +A PR almost always contains more than one commit, and not all of them are worth your attention. The classic example is a new-version PR like PR #121: one commit _scaffolds_ the version folder (a boilerplate copy of the previous version — hundreds of files, zero real content) and a second commit holds the actual edits you should review. If you open the **Files changed** tab without narrowing the diff first, you'll be drowning in 200+ files of scaffolding. Don't. + +The **Commits** tab is where you confirm the structure of the PR: + + + +_(1) The **Commits** tab itself — this is the view you're on. (2) The scaffolding commit (`85e53a4`). Its message — "Scaffold v1.1 of RMC TotalRisk Users Guide" — and its 219-file footprint flag it as the boilerplate. Skip it. (3) The content commit (`7ae2022`). Its message lists what was actually edited: preface, installation, GUI, acronyms. This is the commit you came to review. (4) The short SHA on the right is a clickable link — clicking it jumps to a view of just that commit's diff._ + +Once you know which commit holds the content, switch to the **Files changed** tab and narrow the diff to that commit only: + + -## Leaving feedback +_(1) You're on the **Files changed** tab. (2) The commit selector in the top left — by default it says "All commits"; clicking it lets you pick a single commit. Here it's narrowed to `Commit 7ae2022`. (3) The file tree, now showing only the four files the content commit touched (instead of the 219 from the scaffolding commit). (4) The diff of the first file, where you can scan the actual edits. (5) The **Submit review** button — you'll use this later, after leaving comments._ + +The animation below shows the commit selector in action: + + + +_Opening the commit selector and selecting the content commit — the file tree on the left collapses from 219 files down to 4._ + +A note for authors reading this chapter: writing clear, descriptive commit messages is how you make a reviewer's life easier. "Scaffold v1.1" and "Update preface, installation, GUI, and acronyms for v1.1" are both unambiguous about what each commit contains. See the Author Workflow chapter for the full commit-message guidance. + +:::tip Checkpoint +You can navigate the four PR tabs, recognize the three bot comments, find the **Preview deployed** link, and narrow the Files changed view to a single commit. +::: + +--- + +### 4. Reading the document on the preview site + +Click the URL in the **Preview deployed** bot comment. It opens the rendered document on an unadvertised preview site that looks identical to the production site but contains the in-review revision. + + + + + (1) The same site chrome as the production docs — same header, same navigation, same styling. (2) The document's section sidebar on the left, + identical to what readers see live. (3) The breadcrumb showing where you are in the document. (4) The article body, formatted exactly as readers + will see it after merge. + + +**Read from this page.** This is the source of truth for your review. The Files changed tab on the PR shows the raw MDX source code, which is dense and easy to misread; the preview site shows what the author actually intends readers to see. Read the document end to end, the same way a regular reader would. + +:::tip Checkpoint +You've opened the preview URL from the bot comment and read the in-review document end to end. +::: + +--- + +### 5. Leaving your first comment + +This is the longest section of the chapter, because comments are the heart of the review. The mechanics aren't difficult, but several pieces of the GitHub UI are easy to miss the first time through. Read this section linearly the first time — you can come back to individual subsections later as reference. + +#### Switching to the Files changed tab + +Comments on a PR can only be left on the **Files changed** tab. You cannot leave a comment on the preview site, and you cannot leave a _line-anchored_ comment on the Conversation tab. (You can post a general comment on the Conversation tab, but that's separate from review comments and rarely what you want.) Switch to the **Files changed** tab now, with the commit selector narrowed to the content commit as you did in Section 3. + +#### Understanding what you're looking at — the diff + +The Files changed tab shows a **diff** — a comparison between the current version of each file on the branch and what was there before. Three colors matter: -On the PR's **Files changed** tab, hovering over a line displays a blue "+" icon that opens a comment box on click. +- **Green lines** are additions. They didn't exist before this commit; they do now. +- **Red lines** are removals. They existed before; this commit deleted them. +- **White (unchanged) lines** are context. They surround the changes so you can see them in their natural setting. -- **Plain comment.** Type the feedback and click **Start a review** (first comment) or **Add review comment** (subsequent comments). -- **Suggested change.** The "±" icon in the comment toolbar inserts a pre-filled code block. Editing the block to the proposed wording lets the author accept the suggestion with one click. +For a brand-new file (typical for a new-document PR), the entire file is green — every line is an addition. For a minor revision, only the changed paragraphs are colored, and the rest of the file is white. -## Submitting the review +If a line was **edited** rather than added or removed outright, you'll see the old version in red immediately followed by the new version in green. The pair is logically one change: the author swapped one line for another. -The **Finish your review** button (upper right of the Files changed tab) opens the submit dialog. The reviewer chooses one of three options. +#### Unified vs. split view + +By default GitHub shows the diff as a single column with the red and green lines stacked vertically — that's the **unified view**. For long prose paragraphs this is often hard to read, because the old and new versions of a sentence end up on separate lines and you have to compare them mentally. + +GitHub also offers a **split view** that places the old version on the left and the new version on the right. For documentation reviews — where most changes are prose edits, not code — split view is usually easier. Toggle between the two by clicking the **gear icon** in the top right of the diff area and choosing **Split** or **Unified**. Your choice persists across PRs. + + + +#### Reading MDX without panic + +The diff shows raw MDX source — Markdown plus React component tags. If you've never seen MDX before, the angle-bracket components (`
`, ``, ``) can look like a wall of code. Don't panic. The diff format is for verifying _what_ the author changed; the **preview site** is where you verify _how it looks_. If the preview reads correctly and the right figures, tables, and equations render in the right places, the MDX is doing its job — you don't need to evaluate it line by line. + +A few MDX patterns you'll see repeatedly: <Figure figKey="..." src="..." caption="..." />', + '<Equation>...</Equation>', + '<Citation citationKey="..." />', + '**bold** and *italic*', ], [ - 'Notes have been left for the author to address. Used for every review round that produces feedback.', - 'The document is satisfactory, typically on a backcheck round after prior comments were addressed.', - 'Not used in this workflow.', + 'An image with a numbered caption.', + 'A mathematical equation rendered with LaTeX.', + 'A literature citation; renders as a bracketed number in the prose.', + 'Bold text and italic text respectively.', ], + ]} + colWidths={['40%', '60%']} +/> + +If something in the rendered preview looks wrong and you can't tell whether it's a content mistake or an MDX mistake, **describe what you see on the preview and leave the diagnosis to the author.** "The figure number jumped from 3 to 5" is a useful comment; you don't need to know which line of MDX is responsible. + +#### Leaving a comment on a single line + +To comment on a specific line, hover that line in the diff. A small blue **+** icon appears in the gutter to the left of the line number. Click it. A comment composer opens directly underneath the line. + + + +_Hover the line → blue **+** appears in the gutter → click → composer opens. Type your comment in the textarea, then choose how to submit it (covered below)._ + +A few things to know about the composer: + +- **The textarea accepts Markdown.** `**bold**` renders as **bold**, `*italic*` as _italic_, backticks for `inline code`, blank lines for paragraph breaks, and `>` at the start of a line for a quoted block. These are the same primitives used in the documents themselves, so they're worth getting comfortable with. +- **The toolbar above the textarea** has buttons for headings, bold, italic, lists, quotes, code, and links. You can use the toolbar to format your comment without remembering Markdown syntax. +- **Drag-and-drop or paste an image** into the textarea to attach a screenshot. Useful when you want to show the author exactly what looks wrong on the preview. +- **There are three buttons at the bottom of the composer.** Which one you click matters — see "Comment vs. Start a review" below. + +#### Commenting on multiple lines + +You can comment on a _range_ of lines, not just one. After the blue **+** appears on hover, click and **drag down the gutter** to select multiple lines. The composer that opens is anchored to the whole range, and the author sees the range highlighted when they read the comment. Useful for "this entire paragraph needs to be reworded" rather than dropping the same comment on five consecutive lines. + + + +_Click the blue **+**, then drag down to select a range. Release to open the composer for the whole range._ + +#### Comment vs. Start a review — the fork that confuses everyone + +Three buttons sit at the bottom of the composer: **Cancel**, **Comment**, and **Start a review**. **Cancel** closes the composer without posting; the other two both post the comment, but they behave very differently. + +Comment', 'Start a review'], [ - 'Stage does not advance.', - 'Advances the stage (if the approver matches the assigned reviewer list).', - '—', + 'Posts the comment immediately and emails the author right then. No batching.', + 'Saves your comment as pending — the author cannot see it yet. Each subsequent comment is queued the same way until you submit the whole batch.', + ], + [ + 'Only when you are leaving exactly one comment and stopping (e.g. “the preview link looks broken, pinging you before I keep going”).', + 'Almost every review. One notification to the author when you finish, not one per comment.', ], ]} + colWidths={['20%', '40%', '40%']} /> -The typical cycle is: leave notes via **Comment** → the author addresses them and pushes revisions → the stage progression bot pings the reviewer to backcheck → the reviewer returns and submits **Approve** if satisfied (or another **Comment** review with additional feedback). +**Default to Start a review unless you have a specific reason not to.** Sending the author 17 separate email notifications across an hour of review is rude; one consolidated notification at the end is what they want. + +#### Replying to comments and follow-up discussion + +Reviews aren't one-way. The author will often reply to your comment asking for clarification — "do you mean Section 4 or Appendix A?" — and you should answer. Each comment has a **Reply…** box directly underneath it. Type your response and click **Comment** to post. -## After approval +Replies post immediately by design: they're conversational, the author is already in the thread, and queuing replies inside a batch would be confusing. The Reply box doesn't offer a **Start a review** option — only a single **Comment** button. -The stage progression workflow advances the PR automatically only if the approver was the reviewer the site administrator assigned for the current stage. The workflow uses per-individual gating: it compares the approver's username to the list of reviewers the administrator assigned via the Reviewers sidebar, and only advances the stage when one of those assigned reviewers approves. An approval from a reviewer who was not assigned to the PR is acknowledged by the bot but does not advance the stage. +If a thread gets long, summarize the conclusion in a final reply so a future reader doesn't have to scroll through the back-and-forth to find what was decided. + +#### Resolving threads + +When the author has addressed a comment — either by changing the document or by replying with an explanation you accept — the thread should be **resolved**. Each comment thread has a **Resolve conversation** button at the bottom. + + + +_Resolving a thread collapses it visually. The contents are still there — anyone can expand the thread again — but it stops drawing the eye._ + +The convention in this project: **the author resolves threads** after pushing the fix or replying. The reviewer **re-opens** a thread if the author's response wasn't sufficient. This division of labor avoids confusion about who's responsible. All threads must be resolved before the PR is merged. + +#### Editing or deleting your own comment + +You'll occasionally post a comment, immediately notice a typo, and want to fix it. Each comment has a **`…`** menu in the top right; **Edit** lets you correct the text, and **Delete** removes the comment entirely. + + + +_The `…` menu in the top right of each comment. Edit and Delete are the only two options you'll use day to day._ + +Use **Edit** for typos and minor wording fixes. Use **Delete** if you posted something you regret or that became irrelevant — but note that the author may have already seen the email notification, so a follow-up "ignore my previous comment, withdrawing it" reply is often kinder than a silent delete. + +:::tip Checkpoint +You've left at least one comment as part of a pending review batch, and you understand the difference between **Start a review** and **Comment**. You can also reply to threads, resolve conversations, and edit or delete your own comments. +::: + +--- + +### 6. Submitting your review + +Once you've left every comment you intend to leave, you submit the review. Click the green **Finish your review** button in the top right of the Files changed tab. A dialog opens. + + + +_(1) The dialog title. (2) An optional text area for an overall review message — leave a short summary here, like "Three minor wording notes; otherwise looks great." (3) The **Comment** radio button: submits your batched comments without taking a position on whether to merge. (4) The **Approve** radio button: submits the comments and signals you're happy for the PR to advance. (5) The **Request changes** radio button: not used in this workflow. (6) The **Submit review** button at the bottom — clicking this posts the batch._ + +Choose the radio that matches the situation: + +- **Comment** is the default for every round that leaves feedback. You're saying "here are my notes" without committing to approve or block. Use this on the first review round. +- **Approve** is what you click on a later round — typically a backcheck after the author has addressed your earlier comments — when you're satisfied with the document. +- **Request changes** is not used in this workflow. It's the same as **Comment** mechanically but adds an explicit "blocking" flag that complicates the stage-progression logic. Just leave comments and submit as **Comment**; the author will see the notes and respond. + + + +_Click **Finish your review** → choose **Comment** or **Approve** → click **Submit review**. The pending comments post all at once._ + +:::tip Checkpoint +Your review is submitted. All of your pending comments are now visible to the author, the bot has acknowledged the review with a new comment on the Conversation tab, and you've earned a break. +::: + +--- + +### 7. The backcheck round + +After you submit a **Comment** review, the author addresses your notes by pushing new commits to the branch. The stage-progression bot then pings you — by email and by GitHub notification — to come back and look at what changed. This second pass is called a **backcheck**. + +Reload the PR. The Files changed tab now contains everything the author has done on the branch — both your already-reviewed changes and the new commits. You don't want to re-read material you've already reviewed; you only want to see what's new since your last review. + +The commit selector you used in Section 3 has a special option for exactly this: **Changes since your last review.** It filters the diff to show only commits the author has pushed after the timestamp of your most recent submitted review. + + + +_Open the commit-range dropdown → select **Changes since your last review**. The diff collapses to only what's new since you last submitted, so you can focus on the author's fixes without re-reading the whole document._ + +Review the new commits the same way you reviewed the original: read the affected sections on the preview site, then leave any comments on the Files changed tab. If you have nothing new to say and the fixes look good, open **Finish your review** and choose **Approve** this time. Provide a short message and click **Submit review**. + +:::tip Checkpoint +You know how to filter the Files changed tab to **Changes since your last review**, and you've approved (or left another round of comments) on the author's revisions. +::: + +--- -If the site administrator assigned multiple people at the same stage, the first approval from any of them advances the stage — all assigned reviewers do not need to approve. +### 8. You're done -The reviewer does not need to take further action unless tagged in a follow-up question. +The moment you click **Submit review**, the Conversation tab updates. A new timeline event appears with your username, your overall message (if you typed one), and a link to the changes you reviewed. -## New commits after approval +If your review was an **Approve** and you were the assigned reviewer for the current stage, the stage-progression bot will post a new comment confirming that the stage has advanced. The PR now moves to the next review lane (or, if you were the last reviewer needed, to the **ready-to-merge** state). You don't have to do anything else. -When the author pushes new commits after a reviewer approves, GitHub dismisses the approval in the UI so the green checkmark disappears. The stage progression bot, however, does not reset the stage label — the document stays at its current review stage (e.g., `stage:peer-review`) and the bot pings the reviewer to backcheck the revisions. The reviewer reviews the changes and submits another review: **Approve** if satisfied, or another **Comment** review with additional feedback. +If you receive another notification later — for example, a follow-up question or a new commit — you'll come back and treat it as another backcheck round. Otherwise, your work on this PR is finished. diff --git a/docs/dev/documentation-guide/15-site-admin-workflow.mdx b/docs/dev/documentation-guide/15-site-admin-workflow.mdx index 1de50b9e2..f94723371 100644 --- a/docs/dev/documentation-guide/15-site-admin-workflow.mdx +++ b/docs/dev/documentation-guide/15-site-admin-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. diff --git a/planning/01-repo-implementation.md b/planning/01-repo-implementation.md deleted file mode 100644 index d34e854a8..000000000 --- a/planning/01-repo-implementation.md +++ /dev/null @@ -1,678 +0,0 @@ -# RMC Software Documentation — Review Process Implementation - -This document describes every structural change to the `usace-rmc/rmc-software-docs` repository for the new review and publishing workflow. Intended for a Claude Code agent or human developer with write access. - -## Review flow overview - -**Lane 1 — New document (two-phase, six-stage review):** - -1. Author opens PR with branch prefix `docs/new/`. Preview workflow publishes to unadvertised preview URL. -2. Peer reviewer reviews on **preview URL**, approves. -3. RMC Lead Civil reviews on **preview URL**, approves. -4. AI technical edit: someone with Claude Code runs `/technical-edit`, which reads the source MDX and posts inline review comments on the PR. Author addresses comments, checks a checkbox in the PR description to confirm completion. **No live deploy at this stage** — the technical edit works on source files. -5. Site admin triggers checkpoint deploy of PR branch to **production URL** (watermarked). This is the first time the document appears on the live site. -6. Director reviews on **live URL**, approves with one click. -7. Site admin flips draft flag to `false`, merges PR to `main`, approves final deploy (watermark removed). - -**Lane 2 — Major revision:** - -1. Author opens PR with `docs/major/`. Preview workflow publishes to preview URL. -2. Peer reviewer reviews on preview URL, approves. -3. RMC Lead Civil reviews on preview URL, approves. -4. AI technical edit: someone runs `/technical-edit`, author addresses comments and checks the completion checkbox. -5. Site admin flips draft flag, merges to `main`, approves final deploy. - -**Lane 3 — Minor revision:** - -1. Author opens PR with `docs/minor/`. Preview workflow publishes to preview URL. -2. Peer reviewer reviews on preview URL, approves. -3. AI technical edit: someone runs `/technical-edit`, author addresses comments and checks the completion checkbox. -4. Site admin flips draft flag, merges to `main`, approves final deploy. - -**Lane 4 — Editorial fix:** Site admin reviews on preview URL, merges and deploys. No formal review. - -**Key architectural notes:** -- The deploy workflow supports deploying from arbitrary branches (not just `main`) for Lane 1 checkpoint deploys. -- `main` does not always equal what's on the live site during Lane 1 reviews. -- The AI technical edit stage advances when the author checks a task list checkbox in the PR description, not when a reviewer clicks approve. -- The stage progression workflow only auto-processes PRs whose branch name starts with `docs/`. PRs from any other branch (infrastructure, tooling, dependency bumps, etc.) are silently ignored — no labels, no comments, no review-process noise. A site admin can still pull any PR into the review process by manually applying a `lane:*` label, which is the escape hatch for mis-named branches or one-off cases. -- The PR preview workflow (`pr-preview.yml`) uses a broader path-based trigger and will build a preview for any PR that touches doc-relevant files, regardless of branch prefix. This is intentional: previews are useful for verifying non-doc changes (e.g., a config tweak) even when no formal review is required. -- The required-status-checks list on `main` should contain only checks that always run on PRs. The right checks to require are `CI Build` (from `ci-build.yml`, runs on every PR) and `Manage review stage` (from `stage-progression.yml`, runs on every PR and silent-exits on non-`docs/` branches). **Do not add `Build site` (from `deploy.yml`) or `Build and deploy preview` (from `pr-preview.yml`) as required checks** — the former never runs on PRs and the latter only runs on path-matching PRs, so requiring them blocks PRs forever waiting for results that aren't coming. - -## Scope - -This implementation adds: -1. Version-aware draft watermark logic -2. `.github/` directory: workflows, templates, CODEOWNERS -3. `docusaurus.config.js` env-var update for preview builds -4. Claude Code skills: `/new-revision` and `/technical-edit` - -Does **not** include: GitHub team creation, preview repo creation, branch protection, environment rules, or user-facing MDX documentation. - ---- - -## Task 1: Update the draft watermark logic - -**File:** `src/theme/DocItem/index.js` - -Replace the entire file with: - -```js -import React from "react"; -import DocItem from "@theme-original/DocItem"; -import { useLocation } from "@docusaurus/router"; -import { draftDocs } from "../../draftDocs"; -import latestVersions from "@site/static/versions/latestVersions.json"; - -function getDocInfo(pathname) { - const stripped = pathname - .replace(/^\/RMC-Software-Documentation\/docs\//, "") - .replace(/^\/docs\//, "") - .replace(/^docs\//, ""); - const match = stripped.match(/^(.+?)\/(v\d+\.\d+(?:\.\d+)?)(?:\/|$)/); - if (!match) return null; - return { docBasePath: match[1], version: match[2] }; -} - -function isDraftDoc(pathname) { - const info = getDocInfo(pathname); - if (!info) return false; - const isFlagged = draftDocs.some( - (base) => info.docBasePath === base || info.docBasePath.startsWith(base + "/") - ); - if (!isFlagged) return false; - const latest = latestVersions[info.docBasePath]; - if (!latest) return true; - return info.version === latest; -} - -export default function DocItemWrapper(props) { - const location = useLocation(); - const showWatermark = isDraftDoc(location.pathname); - return ( - <> - {showWatermark && ( -
- DRAFT -
- )} - - - ); -} -``` - ---- - -## Task 2: Update `docusaurus.config.js` - -Replace the `url` and `baseUrl` lines: - -```js - url: process.env.DOCUSAURUS_URL || 'https://USACE-RMC.github.io', - baseUrl: process.env.DOCUSAURUS_BASE_URL || '/RMC-Software-Documentation/', -``` - ---- - -## Task 3: Create `.github/` directory - -### 3.1 `.github/CODEOWNERS` - -``` -/.github/ @usace-rmc/docs-admin -/docusaurus.config.js @usace-rmc/docs-admin -/tailwind.config.js @usace-rmc/docs-admin -/package.json @usace-rmc/docs-admin -/package-lock.json @usace-rmc/docs-admin -/scripts/ @usace-rmc/docs-admin -/src/theme/ @usace-rmc/docs-admin -/src/pages/ @usace-rmc/docs-admin -/src/components/ @usace-rmc/docs-admin -/src/contexts/ @usace-rmc/docs-admin -/src/clientModules/ @usace-rmc/docs-admin -/src/css/ @usace-rmc/docs-admin -/src/draftDocs.js @usace-rmc/docs-admin -``` - -### 3.2 `.github/pull_request_template.md` - -```markdown -## Description - - - -## Affected documents - -- - -## Related issue(s) - - - -## Pre-submission checklist - -- [ ] I have previewed these changes locally or via the PR preview URL -- [ ] My branch name uses one of the expected prefixes: `docs/new/`, `docs/major/`, `docs/minor/`, or `docs/fix/` -- [ ] I have updated `00-version-history.mdx` if this change warrants a version entry -- [ ] I have assigned a specific peer reviewer via the Reviewers sidebar (if known) - -## Technical edit (Lane 1 only) - -- [ ] Technical edit comments addressed — ready for Director review - -## Notes for reviewers - - -``` - -### 3.3 `.github/workflows/deploy.yml` - -```yaml -name: Deploy to GitHub Pages - -on: - push: - branches: [main] - workflow_dispatch: - inputs: - ref: - description: 'Branch or ref to deploy (leave blank for main)' - required: false - type: string - -permissions: - contents: read - pages: write - id-token: write - -concurrency: - group: pages - cancel-in-progress: false - -jobs: - build: - name: Build site - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - with: - ref: ${{ inputs.ref || github.ref }} - - uses: actions/setup-node@v4 - with: - node-version: '20' - cache: 'npm' - - run: npm ci - - run: npm run build - - uses: actions/upload-pages-artifact@v3 - with: - path: ./build - - deploy: - name: Deploy to production - needs: build - runs-on: ubuntu-latest - environment: - name: production - url: ${{ steps.deployment.outputs.page_url }} - steps: - - name: Deploy to GitHub Pages - id: deployment - uses: actions/deploy-pages@v4 -``` - -### 3.4 `.github/workflows/pr-preview.yml` - -```yaml -name: PR Preview Build - -on: - pull_request: - types: [opened, synchronize, reopened] - paths: - - 'docs/**' - - 'src/**' - - 'static/**' - - 'docusaurus.config.js' - - 'tailwind.config.js' - - 'package.json' - - 'package-lock.json' - - 'scripts/**' - -permissions: - contents: read - pull-requests: write - -jobs: - build-and-deploy: - name: Build and deploy preview - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - uses: actions/setup-node@v4 - with: - node-version: '20' - cache: 'npm' - - run: npm ci - - name: Build site with PR-specific baseUrl - env: - DOCUSAURUS_URL: https://usace-rmc.github.io - DOCUSAURUS_BASE_URL: /RMC-Software-Documentation-Previews/pr-${{ github.event.pull_request.number }}/ - run: npm run build - - uses: peaceiris/actions-gh-pages@v4 - with: - deploy_key: ${{ secrets.PREVIEW_DEPLOY_KEY }} - external_repository: usace-rmc/RMC-Software-Documentation-Previews - publish_branch: gh-pages - publish_dir: ./build - destination_dir: pr-${{ github.event.pull_request.number }} - keep_files: true - user_name: 'github-actions[bot]' - user_email: 'github-actions[bot]@users.noreply.github.com' - commit_message: 'Deploy preview for PR #${{ github.event.pull_request.number }}' - - name: Post or update preview URL comment - uses: actions/github-script@v7 - with: - script: | - const prNumber = context.issue.number; - const url = `https://usace-rmc.github.io/RMC-Software-Documentation-Previews/pr-${prNumber}/`; - const marker = ''; - const body = `${marker}\n\n📄 **Preview deployed**\n\n${url}\n\n_This preview updates automatically when new commits are pushed. Deleted when the PR closes._`; - const comments = await github.rest.issues.listComments({ owner: context.repo.owner, repo: context.repo.repo, issue_number: prNumber }); - const existing = comments.data.find(c => c.user.type === 'Bot' && c.body.includes(marker)); - if (existing) { - await github.rest.issues.updateComment({ owner: context.repo.owner, repo: context.repo.repo, comment_id: existing.id, body }); - } else { - await github.rest.issues.createComment({ owner: context.repo.owner, repo: context.repo.repo, issue_number: prNumber, body }); - } -``` - -### 3.5 `.github/workflows/pr-preview-cleanup.yml` - -```yaml -name: PR Preview Cleanup - -on: - pull_request: - types: [closed] - -permissions: - contents: read - -jobs: - cleanup: - name: Delete preview directory - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - with: - repository: usace-rmc/RMC-Software-Documentation-Previews - ref: gh-pages - ssh-key: ${{ secrets.PREVIEW_DEPLOY_KEY }} - - name: Remove PR preview directory - env: - PR_NUMBER: ${{ github.event.pull_request.number }} - run: | - git config user.name "github-actions[bot]" - git config user.email "github-actions[bot]@users.noreply.github.com" - if [ -d "pr-${PR_NUMBER}" ]; then - rm -rf "pr-${PR_NUMBER}" - git add -A - git commit -m "Clean up preview for PR #${PR_NUMBER}" - git push - fi -``` - -### 3.6 `.github/workflows/ci-build.yml` - -Required-status-check workflow that runs on every PR. Builds the site with `npm run build` to catch broken builds before merge. Unlike `deploy.yml` (which only runs on push to main and therefore can't be a meaningful PR check) and `pr-preview.yml` (which is path-conditional and skips non-content PRs), this workflow always runs and is therefore safe to mark as a required check on `main`. - -```yaml -name: CI Build - -on: - pull_request: - types: [opened, synchronize, reopened] - -permissions: - contents: read - -jobs: - build: - name: CI Build - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - uses: actions/setup-node@v4 - with: - node-version: '20' - cache: 'npm' - - run: npm ci - - run: npm run build -``` - -### 3.7 `.github/workflows/stage-progression.yml` - -```yaml -name: Stage Progression - -on: - pull_request: - types: [opened, reopened, labeled, edited] - pull_request_review: - types: [submitted] - -permissions: - pull-requests: write - issues: write - contents: read - -jobs: - progress: - name: Manage review stage - runs-on: ubuntu-latest - steps: - - name: Run stage progression logic - uses: actions/github-script@v7 - with: - script: | - const pr = context.payload.pull_request; - if (!pr) return; - - const prNumber = pr.number; - const branch = pr.head.ref; - const labels = pr.labels.map(l => l.name); - - const LANE_LABELS = ['lane:new-doc', 'lane:major-revision', 'lane:minor-revision', 'lane:editorial-fix']; - const STAGE_LABELS = ['stage:needs-lane', 'stage:peer-review', 'stage:lead-civil-review', 'stage:ai-editor-review', 'stage:director-review', 'stage:ready-to-merge']; - - function detectLane(b) { - if (b.startsWith('docs/new/')) return 'lane:new-doc'; - if (b.startsWith('docs/major/')) return 'lane:major-revision'; - if (b.startsWith('docs/minor/')) return 'lane:minor-revision'; - if (b.startsWith('docs/fix/')) return 'lane:editorial-fix'; - return null; - } - - async function addLabels(ls) { if (ls.length) await github.rest.issues.addLabels({ owner: context.repo.owner, repo: context.repo.repo, issue_number: prNumber, labels: ls }); } - async function removeLabel(l) { try { await github.rest.issues.removeLabel({ owner: context.repo.owner, repo: context.repo.repo, issue_number: prNumber, name: l }); } catch(e) {} } - async function postComment(body) { await github.rest.issues.createComment({ owner: context.repo.owner, repo: context.repo.repo, issue_number: prNumber, body }); } - - const existingLane = labels.find(l => LANE_LABELS.includes(l)); - const existingStage = labels.find(l => STAGE_LABELS.includes(l)); - - // ── PR opened/reopened ── - if (context.eventName === 'pull_request' && ['opened', 'reopened'].includes(context.payload.action)) { - // Only auto-process branches under docs/. Non-doc PRs (infrastructure, - // tooling, etc.) are silently ignored on open. An admin can still opt - // any PR into the review process by manually applying a lane:* label, - // which is handled by the labeled-event branch below. - if (!branch.startsWith('docs/')) return; - const lane = existingLane || detectLane(branch); - if (!lane) { - await addLabels(['stage:needs-lane']); - await postComment(`⚠️ **Could not determine review lane**\n\nBranch \`${branch}\` starts with \`docs/\` but does not match an expected sub-prefix (\`docs/new/\`, \`docs/major/\`, \`docs/minor/\`, \`docs/fix/\`).\n\n@usace-rmc/docs-admin please apply the correct \`lane:*\` label.`); - return; - } - const toAdd = [lane]; - let comment; - if (lane === 'lane:editorial-fix') { - toAdd.push('stage:ready-to-merge'); - comment = `📋 **Lane: Editorial Fix**\n\nNo formal review required.\n\n@usace-rmc/docs-admin please review, merge, and approve the deploy.`; - } else { - toAdd.push('stage:peer-review'); - const laneName = lane.replace('lane:', '').replace(/-/g, ' '); - const scope = lane === 'lane:new-doc' ? 'Peer → Lead Civil → Technical Edit → Director' : lane === 'lane:major-revision' ? 'Peer → Lead Civil' : 'Peer review only'; - comment = `📋 **Lane: ${laneName}**\n\nReview scope: ${scope}.\n\nCurrently in **peer review**. If no peer reviewer has been assigned, @usace-rmc/docs-admin please assign one via the Reviewers sidebar.`; - } - await addLabels(toAdd); - await postComment(comment); - return; - } - - // ── Label manually applied ── - if (context.eventName === 'pull_request' && context.payload.action === 'labeled') { - const added = context.payload.label.name; - if (LANE_LABELS.includes(added) && (!existingStage || existingStage === 'stage:needs-lane')) { - await removeLabel('stage:needs-lane'); - if (added === 'lane:editorial-fix') { - await addLabels(['stage:ready-to-merge']); - await postComment(`📋 Lane set to **editorial fix**.\n\n@usace-rmc/docs-admin please review and merge.`); - } else { - await addLabels(['stage:peer-review']); - await postComment(`📋 Lane set to **${added.replace('lane:', '').replace(/-/g, ' ')}**. Moving to peer review.\n\n@usace-rmc/docs-admin please assign the peer reviewer.`); - } - } - return; - } - - // ── PR description edited (check for technical edit checkbox) ── - if (context.eventName === 'pull_request' && context.payload.action === 'edited') { - if (existingStage === 'stage:ai-editor-review' && existingLane === 'lane:new-doc') { - const body = pr.body || ''; - const checkboxChecked = body.includes('[x] Technical edit comments addressed'); - if (checkboxChecked) { - await removeLabel('stage:ai-editor-review'); - await addLabels(['stage:director-review']); - await postComment(`✅ **Technical edit marked complete** by the author.\n\nAdvancing to **Director review**.\n\n@usace-rmc/docs-admin next steps:\n1. Trigger a checkpoint deploy of branch \`${branch}\` via Actions → Deploy to GitHub Pages → Run workflow (this is the first deploy of this PR to the live site, with the DRAFT watermark)\n2. Approve the deploy at the production environment gate\n3. Post the live URL in a comment on this PR\n4. Assign a member of @usace-rmc/docs-director via the Reviewers sidebar\n\nThe Director will review at the live URL. If the Director requests changes and the author pushes fixes, re-trigger the checkpoint deploy to refresh the live URL.`); - } - } - return; - } - - // ── Review approved ── - if (context.eventName === 'pull_request_review' && context.payload.review.state === 'approved') { - if (!existingLane || !existingStage) return; - const reviewer = context.payload.review.user.login; - let nextStage = null, comment = null; - - if (existingLane === 'lane:new-doc') { - if (existingStage === 'stage:peer-review') { - nextStage = 'stage:lead-civil-review'; - comment = `✅ **Peer review approved** by @${reviewer}.\n\nAdvancing to **RMC Lead Civil review**.\n\n@usace-rmc/docs-admin please assign the appropriate Lead Civil via the Reviewers sidebar. The Lead Civil reviews on the preview URL.`; - } else if (existingStage === 'stage:lead-civil-review') { - nextStage = 'stage:ai-editor-review'; - comment = `✅ **Lead Civil review approved** by @${reviewer}.\n\nAdvancing to **technical edit**.\n\n@usace-rmc/docs-admin please run the \`/technical-edit\` Claude Code skill against this PR (or assign a human technical editor). The technical edit reviews the document source MDX directly and posts inline comments on the PR — **no live deploy is needed at this stage**.\n\nAfter the author addresses the technical edit comments and checks the completion checkbox in the PR description, the document will advance to Director review and the site admin will deploy it to the live site (watermarked) at that point.`; - } else if (existingStage === 'stage:director-review') { - nextStage = 'stage:ready-to-merge'; - comment = `✅ **Director review approved** by @${reviewer}.\n\nThis PR is **ready for final merge and publication**.\n\n@usace-rmc/docs-admin next steps:\n1. Check out this branch (locally or via github.dev)\n2. Flip the document's \`draft\` flag to \`false\`\n3. Update \`00-version-history.mdx\` with reviewer and approver names\n4. Commit and push\n5. Merge this PR to \`main\`\n6. Approve the final production deploy in the Actions tab`; - } - } else if (existingLane === 'lane:major-revision') { - if (existingStage === 'stage:peer-review') { - nextStage = 'stage:lead-civil-review'; - comment = `✅ **Peer review approved** by @${reviewer}.\n\nAdvancing to **RMC Lead Civil review**.\n\n@usace-rmc/docs-admin please assign the appropriate Lead Civil via the Reviewers sidebar.`; - } else if (existingStage === 'stage:lead-civil-review') { - nextStage = 'stage:ready-to-merge'; - comment = `✅ **Lead Civil review approved** by @${reviewer}.\n\nThis PR is **ready for final merge**.\n\n@usace-rmc/docs-admin next steps:\n1. Check out this branch\n2. Flip the document's \`draft\` flag to \`false\`\n3. Update \`00-version-history.mdx\`\n4. Commit and push\n5. Merge to \`main\`\n6. Approve the production deploy`; - } - } else if (existingLane === 'lane:minor-revision') { - if (existingStage === 'stage:peer-review') { - nextStage = 'stage:ready-to-merge'; - comment = `✅ **Peer review approved** by @${reviewer}.\n\nThis PR is **ready for final merge**.\n\n@usace-rmc/docs-admin next steps:\n1. Check out this branch\n2. Flip the document's \`draft\` flag to \`false\`\n3. Update \`00-version-history.mdx\`\n4. Commit and push\n5. Merge to \`main\`\n6. Approve the production deploy`; - } - } - - if (nextStage) { - await removeLabel(existingStage); - await addLabels([nextStage]); - await postComment(comment); - } - } -``` - ---- - -## Task 4: Create labels - -| Label | Color | Description | -|---|---|---| -| `lane:new-doc` | `#0E8A16` | New document requiring full review | -| `lane:major-revision` | `#1D76DB` | Major revision | -| `lane:minor-revision` | `#5319E7` | Minor revision | -| `lane:editorial-fix` | `#C5DEF5` | Editorial or grammatical fix | -| `stage:needs-lane` | `#B60205` | Lane could not be determined | -| `stage:peer-review` | `#FBCA04` | Awaiting peer review | -| `stage:lead-civil-review` | `#FBCA04` | Awaiting RMC Lead Civil review | -| `stage:ai-editor-review` | `#FBCA04` | Awaiting technical edit | -| `stage:director-review` | `#FBCA04` | Awaiting Director review | -| `stage:ready-to-merge` | `#0E8A16` | All reviews complete | - ---- - -## Task 5: Create Claude Code skills - -### 5.1 `.claude/skills/new-revision/SKILL.md` - -Create the `/new-revision` skill. (Same content as previously specified — scaffolds a new version folder, sets draft flag, creates appropriately-prefixed branch.) - -### 5.2 `.claude/skills/technical-edit/SKILL.md` - -```markdown ---- -name: technical-edit -description: Run an AI-assisted technical edit on the current PR. Reads all changed MDX files, evaluates them against the RMC technical editing prompt, and posts inline review comments on the PR via the GitHub API. ---- - -# Technical Edit - -Run an AI-assisted technical edit on the current PR's documentation files. - -**Arguments:** `$ARGUMENTS` — optional PR number. If omitted, infer from the current branch. - -## Step 1: Identify the PR and changed files - -Determine the PR number from the current branch (use `gh pr view --json number`). List all changed `.mdx` files in the PR using `gh pr diff --name-only | grep '\.mdx$'`. - -## Step 2: Read the review prompt - -Read the standardized review prompt from `.github/ai-review/technical-editor-prompt.md`. This file contains the full set of review instructions including grammar rules, tense requirements, terminology conventions, Section 508 compliance checks, and style guidelines. - -## Step 3: Review each file - -For each changed MDX file: -1. Read the file contents -2. Apply the review prompt to the file -3. For each finding, record: file path, line number or line range, severity (must-fix / should-fix / suggestion), the issue description, and a suggested fix if applicable - -## Step 4: Post the review on the PR - -Use the GitHub CLI to submit a bundled PR review with inline comments: - -```bash -gh api repos/:owner/:repo/pulls/:pr/reviews \ - --method POST \ - -f body="AI technical edit complete. $(N) comments across $(M) files. Review prompt version: $(VERSION)." \ - -f event="COMMENT" \ - -f comments="[{\"path\": \"...\", \"line\": N, \"body\": \"...\"}]" -``` - -Each comment should be formatted as: -``` -**[severity]** issue description - -> Suggested fix (if applicable) -``` - -Where severity is one of: 🔴 Must fix, 🟡 Should fix, 🔵 Suggestion. - -## Step 5: Report - -Tell the user: -- How many comments were posted -- How many files were reviewed -- Which review prompt version was used -- Remind the author to check the "Technical edit comments addressed" checkbox in the PR description when they're done addressing comments -``` - -### 5.3 `.github/ai-review/technical-editor-prompt.md` - -Create the standardized review prompt: - -```markdown -# RMC Technical Editor Review Prompt - -You are a technical editor reviewing documentation for the U.S. Army Corps of Engineers Risk Management Center (USACE RMC). The documentation is written in MDX (Markdown with JSX) and covers dam safety, levee safety, and related risk analysis topics. - -## Audience - -Practicing dam and levee safety engineers within USACE. These are technical professionals who understand the domain — do not flag correct use of technical terminology as jargon. - -## Review criteria - -### Grammar and mechanics -- Spelling, punctuation, and sentence structure -- Subject-verb agreement -- Correct use of hyphens, em dashes, and en dashes -- Consistent serial comma usage - -### Tense and voice -- Prefer third-person active voice for procedures and descriptions -- Flag passive voice when active would be clearer -- Flag inconsistent tense within a section - -### Clarity and concision -- Flag wordy passages that could be shortened without losing meaning -- Flag ambiguous pronouns or unclear referents -- Flag sentences over 40 words that could be split -- Flag buried leads — key information at the end of a long sentence - -### Terminology consistency -- Flag inconsistent use of terms within the document (e.g., alternating between "embankment" and "dam" when referring to the same structure) -- Do NOT flag correct domain terminology as errors - -### Section 508 accessibility compliance -- Every image must have alt text (check for `alt=` attribute) -- Heading hierarchy must not skip levels (e.g., h2 followed by h4 without h3) -- Link text must be descriptive (flag "click here" or "link" as link text) -- Tables must have header rows -- Lists must use proper markdown list syntax, not manual numbering with plain text -- Color must not be the sole means of conveying information - -### Style consistency -- Figure and table captions must follow a consistent format -- Citations must use the site's citation key format -- Units should be consistent within each document (metric or imperial, not mixed) -- Acronyms must be defined on first use within each chapter - -## Output format - -For each finding, produce: -- The file path and line number(s) -- A severity level: 🔴 Must fix (errors, accessibility violations), 🟡 Should fix (clarity, consistency issues), 🔵 Suggestion (stylistic improvements) -- A clear description of the issue -- A suggested fix where possible (use GitHub suggestion block format) - -## What NOT to flag -- Correct use of technical terminology, even if uncommon -- MDX component syntax (imports, JSX elements) -- Frontmatter fields -- Matters of technical judgment or domain accuracy (that is the peer reviewer's job) -- Alternative phrasings that are equally acceptable -``` - ---- - -## Task 6: Verify and open PR - -1. Run `npm run build` — must succeed. -2. Validate all YAML files. -3. Commit on branch `feature/review-workflow-infrastructure`. -4. Open PR titled: `Add review workflow infrastructure`. - -## Summary checklist - -- [ ] `src/theme/DocItem/index.js` — version-aware watermark -- [ ] `docusaurus.config.js` — env-driven URL/baseUrl -- [ ] `.github/CODEOWNERS` -- [ ] `.github/pull_request_template.md` — includes technical edit checkbox -- [ ] `.github/workflows/deploy.yml` — with `workflow_dispatch` + `ref` input -- [ ] `.github/workflows/pr-preview.yml` — with stale-marker on build failure -- [ ] `.github/workflows/pr-preview-cleanup.yml` -- [ ] `.github/workflows/ci-build.yml` — always-runs PR build check -- [ ] `.github/workflows/stage-progression.yml` — Lead Civil + AI editor + checkbox detection -- [ ] Branch protection on `main` requires `CI Build` and `Manage review stage` (not `Build site` or `Build and deploy preview` — those are not appropriate as required PR checks) -- [ ] `.github/ai-review/technical-editor-prompt.md` -- [ ] `.claude/skills/new-revision/SKILL.md` -- [ ] `.claude/skills/technical-edit/SKILL.md` -- [ ] All 10 labels created -- [ ] Build passes diff --git a/planning/02-documentation-guide-implementation.md b/planning/02-documentation-guide-implementation.md deleted file mode 100644 index 907bd46c1..000000000 --- a/planning/02-documentation-guide-implementation.md +++ /dev/null @@ -1,681 +0,0 @@ -# Documentation Guide Content Implementation — Review and Approval Process - -Seven new chapters for `docs/dev/documentation-guide/` covering the complete review and approval process. Execute after `01-repo-implementation.md` is merged. - -## Task 1: Rename appendix files - -```bash -cd docs/dev/documentation-guide -git mv 09-appendix-a-source-code-structure.mdx 16-appendix-a-source-code-structure.mdx -git mv 10-appendix-b-build-process-overview.mdx 17-appendix-b-build-process-overview.mdx -git mv 11-appendix-c-search-configuration.mdx 18-appendix-c-search-configuration.mdx -``` - -URLs are unchanged because Docusaurus strips numeric prefixes. - -## Task 2: Update `scripts/generateSidebars.js` - -Replace `mainIds` and `appendixIds`: - -```js - const mainIds = [ - '00-introduction', - '01-getting-started', - '02-versioning-system', - '03-project-structure', - '04-creating-new-document-walkthrough', - '05-docx-converter', - '06-creating-editing-pages', - '07-react-components', - '08-troubleshooting-faq', - '09-review-and-approval-overview', - '10-review-lanes', - '11-author-workflow', - '12-reviewer-workflow', - '13-technical-edit', - '14-director-workflow', - '15-site-admin-workflow', - ]; - const appendixIds = [ - '16-appendix-a-source-code-structure', - '17-appendix-b-build-process-overview', - '18-appendix-c-search-configuration', - ]; -``` - -## Task 3: Create the seven chapter files - -All chapters follow existing conventions: `title:` frontmatter only, `NavContainer` import, standard markdown. - ---- - -### 3.1 `09-review-and-approval-overview.mdx` - -```mdx ---- -title: Review and Approval Process Overview ---- - -import NavContainer from '@site/src/components/NavContainer'; - - - -# Review and Approval Process Overview - -This chapter and the six that follow describe the review and approval process for all documentation published on the RMC Software Documentation website. - -## Who participates - -**Author.** Writes or revises the document. The only role assumed to have local development tooling. - -**Peer reviewer.** Subject-matter expert assigned ad-hoc to review technical accuracy. Works entirely in the GitHub web interface. - -**RMC Lead Civil.** Provides technical oversight and quality assurance. Assigned ad-hoc per document. Works in the GitHub web interface. - -**Technical edit (AI-assisted).** An AI-powered editorial review that checks grammar, clarity, tense, terminology, and Section 508 accessibility compliance. A team member triggers the review using a Claude Code skill; the AI posts comments directly on the pull request. A human technical editor can be substituted at the site admin's discretion. - -**Director.** The RMC Director provides final approval for new documents only. Reviews the document on the live site and clicks approve — no file editing required. - -**Site administrator.** Manages reviewer assignments, checkpoint deploys, merge preparation, and final deploys. The only role with access to protected parts of the repository. - -## The five review lanes - -Every change falls into one of five lanes based on its scope: - -**Lane 1: New document.** Peer review → Lead Civil review → Technical edit → Director approval. The peer review, Lead Civil review, and technical edit all happen against the preview URL or the source files. Only after the technical edit completes does the site admin deploy the document to the live site (watermarked) for Director review at the document's final URL. - -**Lane 2: Major revision.** Peer review → Lead Civil review. Entire review happens on the preview site. Site admin deploys the final version after Lead Civil approval. - -**Lane 3: Minor revision.** Peer review only on the preview site. - -**Lane 4: Editorial fix.** Site admin reviews and deploys directly. No formal review. - -**Lane 5: Dev docs.** Any change to documents under `docs/dev/` (developer documentation, guides for contributors, internal references). Treated like Lane 4 — site admin reviews and merges directly, no formal review required. - -## The merge gate - -Every documentation PR has a GitHub commit status called `review-workflow` that functions as the merge gate. Branch protection on `main` requires this status to be `success` before the PR can merge, so nobody — not even a site admin — can merge a PR whose review is incomplete. The stage progression workflow sets this status automatically: - -- **Pending** during any active review stage (`stage:peer-review`, `stage:lead-civil-review`, `stage:ai-editor-review`, `stage:director-review`, or `stage:needs-lane`) -- **Success** when the PR reaches `stage:ready-to-merge`, or immediately on lane assignment for `lane:editorial-fix` and `lane:dev` -- **Success** for non-docs PRs (infrastructure, tooling, dependency updates) as soon as CI Build passes, posted by `ci-build.yml` - -The status is re-evaluated on every push to a PR. The goal is that the merge button reflects the workflow's judgment, not the admin's discretion. - -## The draft watermark - -Documents flagged as drafts display a large diagonal "DRAFT" watermark. For Lane 1, the watermark appears on the live site during the Director review phase only — the document is not deployed to the live site until the technical edit is complete. The watermark signals to any reader who happens to find the live URL that the content is not yet authoritative. The watermark is removed when the site admin flips the draft flag after Director approval. - -For Lanes 2 and 3, the document under revision only exists on the preview site during review. The currently-published version on the live site is never watermarked. - -## Where to go next - -- Authoring a document: read **Review Lanes**, then **Author Workflow** -- Asked to review: read **Reviewer Workflow** -- Running a technical edit: read **Technical Edit** -- Director reviewing a new document: read **Director Workflow** -- Site administrator: read **Site Admin Workflow** -``` - ---- - -### 3.2 `10-review-lanes.mdx` - -```mdx ---- -title: Review Lanes ---- - -import NavContainer from '@site/src/components/NavContainer'; - - - -# Review Lanes - -Every change follows one of five review lanes. The workflow assigns a lane automatically using two signals, in order: - -1. **Content-based detection.** If every documentation file changed in the PR is under `docs/dev/`, the PR is assigned `lane:dev` regardless of branch name. -2. **Branch-name detection.** Otherwise, the branch prefix determines the lane: - -| Branch prefix | Lane | -|---|---| -| `docs/new/` | New document | -| `docs/major/` | Major revision | -| `docs/minor/` | Minor revision | -| `docs/fix/` | Editorial fix | -| `docs/dev/` | Dev docs | - -**Any PR that touches files under `docs/` is processed by the review workflow**, even if its branch name doesn't start with `docs/`. This means a collaborator can accidentally push a documentation change on a branch named `feature/typo-fix` and the workflow will still intercept it at PR open time and ask a site admin to assign a lane. Non-documentation PRs (branches that don't touch anything under `docs/`) are silently ignored by the lane workflow, receive an "admin may merge" comment from `ci-build.yml` once their build passes, and go straight to the merge button. - -If a branch starts with `docs/` but doesn't match one of the five sub-prefixes above (for example, a typo like `docs/newfoo/` or an old-style name like `docs/update`), the workflow applies `stage:needs-lane` and tags a site admin to assign the correct lane manually. The same happens for a PR that touches documentation from a non-`docs/` branch when content-based dev detection doesn't apply. - -A site admin can always override the automatically-detected lane by swapping the `lane:*` label on the PR. The workflow treats a manually-applied lane label the same as an auto-detected one and proceeds normally from there. - -## Lane 1: New document - -**When to use.** Any completely new document being added to the site. - -**Required reviews.** Peer review → RMC Lead Civil review → Technical edit (AI-assisted) → Director approval. - -**What happens.** The document is first visible only on the unadvertised PR preview URL, where peer review, Lead Civil review, and the technical edit all happen (the technical edit reads the source MDX directly via `/technical-edit` and posts inline comments — it does not need a deployed version). Only after the author marks the technical edit complete does the site admin deploy the PR branch to the live production site with the DRAFT watermark. The Director then reviews on the live URL. After Director approval, the site admin flips the draft flag, merges the PR, and deploys the final version — removing the watermark. - -**Example branches:** `docs/new/totalrisk-applications-guide`, `docs/new/lifesim-validation-oroville` - -## Lane 2: Major revision - -**When to use.** Substantial changes to an existing document warranting a new major version (e.g., v1.0 → v2.0). - -**Required reviews.** Peer review → RMC Lead Civil review. - -**What happens.** The entire review happens on the preview URL. The old version stays live and unwatermarked. After Lead Civil approval, the site admin flips the flag, merges, and deploys. The new version becomes the default; the old version is accessible via the version selector. - -**Example branches:** `docs/major/bep-progression-v2.0` - -## Lane 3: Minor revision - -**When to use.** Smaller updates warranting a minor version bump (e.g., v1.0 → v1.1). - -**Required reviews.** Peer review only. - -**What happens.** Same as Lane 2 but without Lead Civil review. - -**Example branches:** `docs/minor/bep-progression-v1.1` - -## Lane 4: Editorial fix - -**When to use.** Typos, broken links, grammatical corrections that don't change technical meaning. - -**Required reviews.** None. Site admin reviews and merges directly. - -**No version change, no watermark.** - -**Example branches:** `docs/fix/bep-progression-typos` - -## Lane 5: Dev docs - -**When to use.** Any new or revised document under `docs/dev/` — developer documentation, contributor guides, internal references, planning documents, and similar materials. - -**Required reviews.** None. Site admin reviews and merges directly, same as Lane 4. - -**Automatic assignment.** The workflow uses content-based detection: if every documentation file changed in the PR is under `docs/dev/`, the PR is assigned `lane:dev` regardless of what the branch is called. This means dev docs can be authored on any branch prefix (including non-`docs/` branches) and still end up in the correct lane. - -**No version change, no watermark.** - -**Example branches:** `docs/dev/ai-development-guide`, `feature/update-contributor-guide` (content detected under `docs/dev/`) - -## Choosing the right lane - -When in doubt, choose the more conservative lane. A site admin can reassign lanes by swapping `lane:*` labels. -``` - ---- - -### 3.3 `11-author-workflow.mdx` - -```mdx ---- -title: Author Workflow ---- - -import NavContainer from '@site/src/components/NavContainer'; - - - -# Author Workflow - -What the author does from start to publication, across all five lanes. - -## Starting work - -### With Claude Code skills - -- **New document (Lane 1):** Run `/new-doc`. Creates branch, scaffolds files, sets draft flag. -- **Revision (Lanes 2/3):** Run `/new-revision`. Copies the latest version to a new version folder, sets draft flag, creates branch. -- **Editorial fix (Lane 4):** Create a `docs/fix/` branch manually and edit files directly. -- **Dev doc (Lane 5):** Create a branch (`docs/dev/` prefix recommended but not required), edit files under `docs/dev/`. The workflow auto-detects the dev lane based on file paths. - -### Without Claude Code - -All steps can be done manually in any IDE, via `git` on the command line, or entirely in the browser using github.dev (press `.` on any GitHub repo page to open a browser-based VS Code). - -**For a new document:** Create a `docs/new/` branch, create the directory structure under `docs/` with a `v1.0/` folder, add boilerplate MDX files, add a landing page JS entry with `draft: true`. - -**For a revision:** Create a `docs/major/-` or `docs/minor/-` branch, copy the current version folder to the new version, set `draft: true` on the landing page entry, add a placeholder version history row. - -## Opening the pull request - -Open a PR via Claude Code (`/pr`) or the GitHub web interface. The PR template prefills a description structure — fill in the sections. Assign your peer reviewer in the Reviewers sidebar if you know who it should be. - -Within minutes, two bot comments appear: a preview URL and a stage progression comment identifying your lane. A third hidden bot comment tracks which individuals the site admin has assigned to each review stage — it renders as an "Assigned reviewers for this PR" block at the top of the PR comment thread. - -## Responding to review comments - -Reviewers post comments on specific lines in the Files changed tab. For each comment: make the fix, push a commit, reply explaining what you did. The reviewer resolves the thread when satisfied. - -For suggested changes (pre-filled code blocks), you can click "Commit suggestion" to apply the fix in one click. - -**All comment threads must be resolved before the PR can merge.** - -## The technical edit (Lane 1) - -After Lead Civil approval, the technical edit stage begins. A team member runs the `/technical-edit` Claude Code skill, which reads the source MDX files directly and posts inline review comments on the PR. These comments cover grammar, tense, clarity, terminology, and Section 508 compliance. **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. - -Address each comment the same way you address human reviewer comments — push fixes, reply, and the site admin or you can resolve threads as they're addressed. - -**When you've addressed all technical edit comments,** check the checkbox in the PR description: - -`- [x] Technical edit comments addressed — ready for Director review` - -Checking this box is what advances the document to Director review. Don't check it until you've addressed all comments. - -## Where reviewers read your document - -For Lane 1: peer review and Lead Civil review happen on the **preview URL**. The technical edit reads the source MDX directly via `/technical-edit` and posts inline comments on the PR — no deploy is involved. Only after you mark the technical edit complete does the site admin deploy the document to the **live production site** (watermarked) for **Director review**. If you push revisions during Director review, the site admin re-deploys so the live URL stays current. - -For Lanes 2 and 3: all review happens on the preview URL only. - -For Lanes 4 and 5: the site admin reviews on the preview URL (if generated) or directly in the Files changed tab, then merges. - -## When reviewers ask for changes - -Reviewers typically submit their feedback as a **Comment** review (not "Request changes"), leaving inline notes on specific lines. Address each comment, push a new commit, and reply to the thread explaining what you did. You don't need to do anything else — the stage progression bot automatically pings the assigned reviewer(s) on your PR to come back and backcheck. - -**The stage does not reset when you push new commits.** A revision during peer review is for the peer reviewer to backcheck; it does not send the document back to start. Same for Lead Civil review and Director review. This is intentional — you're building on the review that already happened, not starting over. - -## When the review is complete - -The site admin prepares the merge: flips the draft flag, updates version history, merges the PR, and approves the final deploy. You'll see email notifications as this happens. Once the deploy completes, your document is live. -``` - ---- - -### 3.4 `12-reviewer-workflow.mdx` - -```mdx ---- -title: Reviewer Workflow ---- - -import NavContainer from '@site/src/components/NavContainer'; - - - -# Reviewer Workflow - -What peer reviewers and RMC Lead Civils do when assigned to review a documentation pull request. Written for someone with little GitHub experience. Everything can be done from a web browser. - -## Prerequisites - -You need a GitHub account and membership in the `usace-rmc` organization. A site administrator will send you an invitation — click the link to accept. - -## Receiving a review request - -GitHub emails you with subject "You were requested to review [title]." Click the link to open the PR. - -## Where to read the document - -**Both peer reviewers and Lead Civils review on the preview URL.** In the PR's comment thread, look for a bot comment that says "Preview deployed" with a URL. Click it. This opens the rendered document on an unadvertised preview site with a DRAFT watermark. - -Read the document as you would any web page. This is where your review happens — you are reading, not editing. - -**Peer reviewers:** Focus on technical accuracy. Are claims correct? Equations right? Procedures complete? - -**Lead Civils:** Focus on technical quality and oversight. Does the document meet RMC standards? Is the scope appropriate? Are conclusions defensible? - -## Leaving feedback - -Click the **Files changed** tab on the PR. Hover over a line to see the blue "+" icon. Click it to open a comment box. - -**Plain comment:** Type your feedback and click "Start a review" (first comment) or "Add review comment" (subsequent). - -**Suggested change:** Click the "±" icon in the comment toolbar. Edit the pre-filled code block to your proposed wording. The author can accept your suggestion with one click. - -## Submitting your review - -Click **Finish your review** (upper right of Files changed). Choose: - -- **Comment** — you've left notes for the author to address. Use this for every review round where you have feedback. The stage does not advance. -- **Approve** — you're satisfied with the document, typically on a backcheck round after the author has addressed your prior comments. **This is what advances the stage.** -- **Request changes** — _not used in this workflow._ Use **Comment** for routine revision cycles. - -Click **Submit review.** - -The typical cycle: you leave notes via **Comment**, the author addresses them and pushes revisions, the stage progression bot pings you to backcheck, and you return to submit **Approve** if satisfied (or another **Comment** review if more feedback is needed). - -## After you approve - -The stage progression workflow advances the PR automatically **if you were the reviewer the site admin assigned for the current stage**. The workflow uses per-individual gating: it compares the approver's username to the list of reviewers the admin assigned via the Reviewers sidebar, and only advances the stage when one of those assigned reviewers approves. If you approve a PR you weren't explicitly assigned to, the bot posts a note acknowledging your approval but doesn't advance the stage. - -If the site admin assigned multiple people at the same stage, the first approval from any of them advances the stage — you don't all need to approve. - -You don't need to do anything further unless someone tags you with a follow-up question. - -## New commits after you approve - -If the author pushes new commits after you approve, GitHub dismisses your approval in the UI so the green checkmark disappears. The stage progression bot, however, does **not** reset the stage label — the document stays at its current review stage (e.g., `stage:peer-review`) and the bot pings you to backcheck the revisions. Take another look at the changes and submit another review: **Approve** if you're satisfied, or another **Comment** review with additional feedback. -``` - ---- - -### 3.5 `13-technical-edit.mdx` - -```mdx ---- -title: Technical Edit ---- - -import NavContainer from '@site/src/components/NavContainer'; - - - -# Technical Edit - -The technical edit is an AI-assisted editorial review that checks the document for grammar, clarity, tense consistency, terminology, and Section 508 accessibility compliance. It is the default editorial review method for new documents (Lane 1). A human technical editor can be substituted at the site admin's discretion. - -## When it happens - -The technical edit occurs after the RMC Lead Civil approves a Lane 1 PR. At this point, the document has already been reviewed for technical accuracy by the peer reviewer and for technical quality by the Lead Civil. The technical edit focuses exclusively on editorial quality and accessibility compliance, and reads the source MDX files directly — **no live deploy is needed at this stage**. The document is only deployed to the live site after the technical edit is complete, and that deploy is for the Director review phase. - -## How it works - -1. A team member with Claude Code access checks out the PR branch and runs `/technical-edit`. -2. Claude reads all changed MDX files and applies a standardized review prompt committed to the repository at `.github/ai-review/technical-editor-prompt.md`. -3. Claude posts inline review comments directly on the PR — on specific lines, with severity levels and suggested fixes — exactly like a human reviewer would. -4. The author addresses each comment: pushes fixes, replies to threads, and resolves conversations as they're addressed. -5. When all comments are addressed, the author checks the checkbox in the PR description: `Technical edit comments addressed — ready for Director review`. -6. The stage progression workflow detects the checkbox and advances the PR to Director review. - -If the technical edit was done by a human or the author isn't available to check the box, a site admin can apply the `admin:advance-to-director` label to the PR as a manual override. The workflow removes the label and advances the stage the same as a checkbox event. - -## What it reviews - -**Grammar and mechanics.** Spelling, punctuation, sentence structure, subject-verb agreement, hyphenation, serial comma usage. - -**Tense and voice.** Third-person active voice consistency. Flags passive voice when active would be clearer. Flags inconsistent tense within sections. - -**Clarity and concision.** Wordy passages, ambiguous pronouns, sentences over 40 words, buried leads. - -**Terminology.** Inconsistent use of terms within the document (e.g., alternating "embankment" and "dam" for the same structure). Does not flag correct domain terminology. - -**Section 508 accessibility.** Image alt text, heading hierarchy (no skipped levels), descriptive link text, table header rows, proper list syntax, color not as sole information channel. - -**Style consistency.** Figure/table caption format, citation key format, unit consistency, acronym definitions on first use. - -## What it does NOT review - -Technical accuracy — that is the peer reviewer's job. Domain conclusions. MDX syntax. Frontmatter fields. - -## The review prompt - -The review prompt is a versioned file in the repository at `.github/ai-review/technical-editor-prompt.md`. It can be updated over time as the team learns what the AI catches well and what it misses. Each AI review comment includes the prompt version used, so comments can be traced back to the exact instructions that generated them. - -## Fallback to a human editor - -A site admin can route any document to a human technical editor instead of (or in addition to) the AI review. The human editor follows the same workflow as peer reviewers and Lead Civils: they're assigned to the PR, review the document on the **preview URL** (the technical edit happens before any live deploy), post comments, and submit their review. The author addresses comments the same way. The only difference is that advancement to Director review requires the human editor to click Approve rather than the author checking the checkbox. - -## Who can run the skill - -Anyone with Claude Code access (a personal Claude subscription) can run `/technical-edit`. The output — the PR review comments — is visible to everyone on GitHub regardless of their subscription status. Only the trigger requires Claude access. - -If nobody with Claude access is available, use the human editor fallback. -``` - ---- - -### 3.6 `14-director-workflow.mdx` - -```mdx ---- -title: Director Workflow ---- - -import NavContainer from '@site/src/components/NavContainer'; - - - -# Director Workflow - -What the RMC Director does when reviewing a new document. The Director's role is intentionally simple: read the document, approve it, move on. The Director only reviews **new documents** (Lane 1). - -## Prerequisites - -1. A GitHub account (sign up at `github.com` if needed). -2. Membership in `@usace-rmc/docs-director` (a site admin adds you; accept the email invitation). - -One-time setup. - -## What you will be asked to do - -When a new document has passed peer review, Lead Civil review, and the technical edit, a site administrator assigns you as a reviewer. GitHub emails you. - -Click the link in the email. On the pull request page, scroll through comments to find one from a **site administrator** containing a URL starting with `https://usace-rmc.github.io/RMC-Software-Documentation/`. This is the **live production site** — the same URL readers will use. - -Click it. The document displays with a DRAFT watermark that will be removed after your approval. - -> **Important:** Use the live URL posted by the site administrator, not the automatic "Preview deployed" bot comment from earlier in the thread. - -Read the document. It has already been reviewed for technical accuracy (peer reviewer), technical quality (Lead Civil), and editorial quality (technical edit). Your review is a final verification that the document meets RMC standards. - -## Approving - -1. Back on the PR, click the **Files changed** tab -2. Click **Review changes** (upper right) -3. Select **Approve** -4. Optionally type a note -5. Click **Submit review** - -Done. The site administrator handles everything from here. - -## If something needs fixing - -Select **Comment** (not Approve or Request changes) and describe the issue. The author will fix it, and the site admin will ask you to re-review. - -For minor suggestions you don't want to block on, select **Approve** and include a note — the site admin will coordinate the follow-up. -``` - ---- - -### 3.7 `15-site-admin-workflow.mdx` - -```mdx ---- -title: Site Admin Workflow ---- - -import NavContainer from '@site/src/components/NavContainer'; - - - -# Site Admin Workflow - -Responsibilities and procedures for site administrators. - -## Responsibilities - -1. Assigning reviewers (peer, Lead Civil, Director) at each stage transition -2. Running checkpoint deploys for Lane 1 PRs -3. Running or coordinating the technical edit -4. Preparing final merge commits (flipping draft flag, updating version history) -5. Merging PRs and approving production deploys -6. Handling Lane 4 editorial fix and Lane 5 dev doc PRs as sole reviewer -7. Resolving edge cases - -## Daily routine - -Check for PRs needing your attention. The stage progression workflow tags `@usace-rmc/docs-admin` at every transition. Filter: `is:open label:"stage:ready-to-merge"` or `is:open review-requested:@me`. - -## Assigning reviewers - -Reviewers are assigned ad-hoc per PR via the Reviewers sidebar (gear icon → type username → select). There are no standing review teams for peer reviewers or Lead Civils. The workflow's transition comment tells you which role to assign next. - -For Lane 1, you assign up to three people across the lifecycle: the peer reviewer (if the author didn't), the Lead Civil after peer approval, and the Director after the technical edit. - -**Per-individual gating.** When you assign 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. You can assign multiple people at the same stage; the first approval from any of them advances the PR. - -If you assigned the wrong person or need to replace someone, remove them from the Reviewers sidebar and add the correct person. The state comment updates automatically. - -## Running a checkpoint deploy (Lane 1) - -After the author marks the technical edit complete (the PR advances to `stage:director-review`), deploy the PR branch to the live site (watermarked) for the Director's review: - -1. Repo → **Actions** tab → click **Deploy to GitHub Pages** in the sidebar -2. Click **Run workflow** dropdown (upper right) -3. Enter the PR branch name in the **ref** field -4. Click **Run workflow** -5. When the build completes, click **Review deployments** → check `production` → **Approve and deploy** -6. Verify the document on the live URL with the watermark -7. Post a comment on the PR with the live URL so the Director knows where to read - -This is the **first** time the document appears on the live site. The peer review, Lead Civil review, and technical edit all happened earlier on the preview URL or against source files; the live deploy is deferred until the document has passed editorial review. - -Re-deploy whenever the author pushes revisions during Director review. Post a comment noting the update. - -## Running the technical edit - -After Lead Civil approval (the PR advances to `stage:ai-editor-review`), run `/technical-edit` from Claude Code while on the PR branch. If you don't have Claude Code access, coordinate with a team member who does. **No deploy is required at this stage** — the technical edit reads the source MDX directly. - -The AI posts inline review comments. The author addresses them and checks the PR description checkbox to advance the PR to Director review, at which point you'll run the checkpoint deploy. - -**Manual override.** If a human technical editor did the review instead, or the author isn't available to check the checkbox, apply the `admin:advance-to-director` label to the PR. The workflow removes the label and advances the stage the same as a checkbox event, then posts the Director-review next-steps comment with instructions for the checkpoint deploy. - -## Preparing the final merge - -When a PR reaches `stage:ready-to-merge`: - -1. Check out the PR branch (locally or via github.dev) -2. In the landing page JS file, change `draft: true` to `draft: false` -3. Update `00-version-history.mdx` with reviewer/approver names -4. Commit and push -5. Merge the PR -6. Approve the final production deploy in Actions - -For Lane 1: `reviewedBy` includes the peer reviewer and Lead Civil; `approvedBy` is the Director. -For Lanes 2/3: `reviewedBy` is the peer reviewer (and Lead Civil for Lane 2); `approvedBy` is `-`. -Lanes 4 and 5: no version history update needed. - -## The `review-workflow` commit status - -Every documentation PR has a `review-workflow` commit status that branch protection on `main` requires to be `success` before the PR can merge. This is the hard merge gate — nobody, including you, can click the merge button until the bot flips this status to success. The bot manages it automatically: - -| Situation | Status | -|---|---| -| `stage:peer-review` / `stage:lead-civil-review` / `stage:ai-editor-review` / `stage:director-review` | pending | -| `stage:needs-lane` (workflow couldn't detect the lane) | pending | -| `stage:ready-to-merge` (all reviews complete) | success | -| `lane:editorial-fix` or `lane:dev` assigned | success (immediately) | -| Non-docs PR, CI Build passed | success (set by `ci-build.yml`) | - -If a PR is stuck because `review-workflow` is pending, check the stage label to figure out what review is outstanding. If a PR is stuck because `review-workflow` is missing entirely (never got set), the lane-detection step probably failed — apply a `lane:*` label manually to re-trigger the workflow. - -## Approving deploys - -Every deploy pauses at the production environment gate. You receive an email. Navigate to Actions → the workflow run → Review deployments → check `production` → Approve and deploy. - -A Lane 1 document may involve multiple deploys: one checkpoint after the technical edit completes (for Director review), optional re-deploys during Director review if the author pushes fixes, and one final deploy after merge. - -## Handling Lane 4 and Lane 5 PRs - -Lane 4 (editorial fix) and Lane 5 (dev doc) PRs skip formal review. You are the reviewer, approver, and merger: - -1. Click the preview URL to see the change -2. Review the Files changed tab -3. Approve, merge, approve the deploy - -The `review-workflow` commit status is flipped to success immediately on lane assignment, so the merge button is enabled as soon as CI finishes. - -## Edge cases - -**Wrong lane:** Remove the current `lane:*` label, apply the correct one. The workflow re-initializes. - -**Branch starts with `docs/` but doesn't match a sub-prefix:** The workflow applies `stage:needs-lane` and tags you. Apply the correct `lane:*` label. - -**Documentation change pushed to a non-`docs/` branch:** The workflow intercepts this at PR open time regardless of branch name, because it detects changes to files under `docs/`. If the content is entirely under `docs/dev/`, it auto-assigns `lane:dev`. Otherwise it applies `stage:needs-lane` and tags you to assign the correct lane manually. Optionally ask the author to rename the branch next time for clarity. - -**Non-documentation PR with no lane comments:** Expected behavior. PRs that don't touch `docs/` are silently skipped by the lane workflow and receive an "admin may merge" comment from `ci-build.yml` when CI passes. This is normal for infrastructure, tooling, and dependency PRs. - -**Unresponsive reviewer:** Ping them on the PR, or remove them from the Reviewers sidebar and assign someone else. The state comment updates automatically. - -**Drive-by approval from an unassigned reviewer:** The workflow posts a note logging the approval but does not advance the stage. If the unassigned approver should actually be advancing the PR, add them as a reviewer via the Reviewers sidebar and ask them to re-approve — the new approval will then match the assigned list and advance the stage. - -**Author pushes new commits during an active review:** Normal and expected. The workflow does not reset the stage. The bot re-sets the `review-workflow` commit status on the new head SHA and pings the assigned reviewer(s) to backcheck. - -**Stale checkpoint deploy:** If the live URL shows outdated content, re-run the checkpoint deploy and post a comment. - -**Build fails on checkpoint deploy:** Coordinate with the author to fix the branch. - -**Build fails after merge to main:** Push a hotfix to `main` or revert the merge. Re-run the deploy. Note that `deploy.yml` filters by paths — a merge that doesn't touch any site-affecting files (`docs/`, `src/`, `static/`, `scripts/`, `docusaurus.config.js`, `tailwind.config.js`, `package.json`, `package-lock.json`) does not trigger a redeploy, so a broken workflow or documentation change to the planning folder won't break the live site. - -**Need to force a production redeploy:** Go to Actions → Deploy to GitHub Pages → Run workflow, specify the ref (usually `main`), and approve at the production gate. This is the escape hatch when the path filter would otherwise skip a merge that actually needs to ship. - -## Onboarding new site admins - -1. Clone the repo, confirm local build works -2. Read these Documentation Guide chapters -3. Shadow an existing admin through one full PR lifecycle -4. Practice on a Lane 4 editorial fix PR -``` - ---- - -## Infrastructure notes (for reference — not part of any chapter) - -The following are in place in the repository and support the workflow described above. Recording them here so future planning documents and Claude Code sessions have a reference. - -### Repository labels - -Created on `USACE-RMC/RMC-Software-Documentation`: - -- `lane:new-doc`, `lane:major-revision`, `lane:minor-revision`, `lane:editorial-fix`, `lane:dev` -- `stage:needs-lane`, `stage:peer-review`, `stage:lead-civil-review`, `stage:ai-editor-review`, `stage:director-review`, `stage:ready-to-merge` -- `admin:advance-to-director` - -### Branch protection on `main` - -Required status checks: `CI Build`, `review-workflow`. Stale approvals dismissed on new pushes. Conversation resolution required. Force pushes and branch deletion disallowed. - -### Workflow files - -- `.github/workflows/ci-build.yml` — runs `npm run build` on every PR; flips `review-workflow` commit status to success for non-docs PRs -- `.github/workflows/pr-preview.yml` — builds and deploys preview to the `usace-rmc/RMC-Software-Documentation-Previews` repo; filters by paths (only affects PRs that touch site-affecting files); sets `DOCUSAURUS_IS_PREVIEW=true` so Google Analytics is disabled for preview builds; has a per-PR concurrency block that cancels superseded builds -- `.github/workflows/pr-preview-cleanup.yml` — deletes the PR's preview directory when the PR closes -- `.github/workflows/deploy.yml` — production deploy on merge to `main`; filters by the same paths allowlist as `pr-preview.yml` so merges that don't affect site output skip the redeploy; uses `actions/deploy-pages@v4` artifact flow (no `gh-pages` branch); gated by a `production` GitHub environment that requires admin approval -- `.github/workflows/stage-progression.yml` — the core review-workflow logic: lane detection, state-comment management, stage transitions, commit status management, admin override handling; has a per-PR concurrency block - -### Lane detection logic - -1. **Content-based first:** if every docs file in the PR is under `docs/dev/`, assign `lane:dev` -2. **Branch-name fallback:** match branch prefix against `docs/new/`, `docs/major/`, `docs/minor/`, `docs/fix/`, `docs/dev/` -3. **Manual:** if neither matches and the PR touches `docs/`, apply `stage:needs-lane` and ping admin - -### State comment format - -Hidden bot comment on each PR with marker ``. Contains a JSON data line (``) that maps each active review stage to an array of assigned reviewer usernames. Updated on `review_requested` and `review_request_removed` webhook events. Read on `pull_request_review` approval events to check whether the approver is in the assigned list for the current stage. - -### Google Analytics exclusion for previews - -`pr-preview.yml` sets `DOCUSAURUS_IS_PREVIEW=true` in the build environment. `docusaurus.config.js` checks this and excludes the `@docusaurus/plugin-google-gtag` plugin when set, so preview page views don't pollute the production GA property. Production builds (`deploy.yml`, local `npm run build`) don't set this variable, so they behave normally. - ---- - -## Task 4: Verify - -1. Run `npm run sidebars` to regenerate sidebar -2. Run `npm run build` — must succeed -3. Run `npm start` and verify all seven new chapters appear in order -4. Confirm renamed appendices still appear at the bottom - -## Task 5: Open the PR - -Branch: `docs/new/documentation-guide-review-chapters` - -PR title: `Add review and approval process chapters to Documentation Guide` - -## Checklist - -- [ ] Three appendix files renamed -- [ ] `scripts/generateSidebars.js` updated -- [ ] Seven new chapter MDX files created -- [ ] `npm run sidebars` run -- [ ] Build passes -- [ ] Visual check passes -- [ ] PR opened diff --git a/static/figures/dev/reviewer-workflow/fig-01-email.png b/static/figures/dev/reviewer-workflow/fig-01-email.png new file mode 100644 index 000000000..a7ee6e78e Binary files /dev/null and b/static/figures/dev/reviewer-workflow/fig-01-email.png differ diff --git a/static/figures/dev/reviewer-workflow/fig-02-pr-overview.png b/static/figures/dev/reviewer-workflow/fig-02-pr-overview.png new file mode 100644 index 000000000..c3f09aae3 Binary files /dev/null and b/static/figures/dev/reviewer-workflow/fig-02-pr-overview.png differ diff --git a/static/figures/dev/reviewer-workflow/fig-03-pr-commits.png b/static/figures/dev/reviewer-workflow/fig-03-pr-commits.png new file mode 100644 index 000000000..fc9a48f09 Binary files /dev/null and b/static/figures/dev/reviewer-workflow/fig-03-pr-commits.png differ diff --git a/static/figures/dev/reviewer-workflow/fig-04-pr-files-changed.png b/static/figures/dev/reviewer-workflow/fig-04-pr-files-changed.png new file mode 100644 index 000000000..ac4731ce8 Binary files /dev/null and b/static/figures/dev/reviewer-workflow/fig-04-pr-files-changed.png differ diff --git a/static/figures/dev/reviewer-workflow/fig-05-bot-comments.png b/static/figures/dev/reviewer-workflow/fig-05-bot-comments.png new file mode 100644 index 000000000..eebac9aca Binary files /dev/null and b/static/figures/dev/reviewer-workflow/fig-05-bot-comments.png differ diff --git a/static/figures/dev/reviewer-workflow/fig-06-preview-page.png b/static/figures/dev/reviewer-workflow/fig-06-preview-page.png new file mode 100644 index 000000000..3a781e610 Binary files /dev/null and b/static/figures/dev/reviewer-workflow/fig-06-preview-page.png differ diff --git a/static/figures/dev/reviewer-workflow/fig-08-finish-review.png b/static/figures/dev/reviewer-workflow/fig-08-finish-review.png new file mode 100644 index 000000000..8963fd4e6 Binary files /dev/null and b/static/figures/dev/reviewer-workflow/fig-08-finish-review.png differ diff --git a/static/figures/dev/reviewer-workflow/gif-01-fallback.gif b/static/figures/dev/reviewer-workflow/gif-01-fallback.gif new file mode 100644 index 000000000..f6147c116 Binary files /dev/null and b/static/figures/dev/reviewer-workflow/gif-01-fallback.gif differ diff --git a/static/figures/dev/reviewer-workflow/gif-changes-since-last-review-storyboard.gif b/static/figures/dev/reviewer-workflow/gif-changes-since-last-review-storyboard.gif new file mode 100644 index 000000000..88e87107e Binary files /dev/null and b/static/figures/dev/reviewer-workflow/gif-changes-since-last-review-storyboard.gif differ diff --git a/static/figures/dev/reviewer-workflow/gif-commit-filter-storyboard.gif b/static/figures/dev/reviewer-workflow/gif-commit-filter-storyboard.gif new file mode 100644 index 000000000..89ca395a3 Binary files /dev/null and b/static/figures/dev/reviewer-workflow/gif-commit-filter-storyboard.gif differ diff --git a/static/figures/dev/reviewer-workflow/gif-composer-storyboard.gif b/static/figures/dev/reviewer-workflow/gif-composer-storyboard.gif new file mode 100644 index 000000000..33bad392a Binary files /dev/null and b/static/figures/dev/reviewer-workflow/gif-composer-storyboard.gif differ diff --git a/static/figures/dev/reviewer-workflow/gif-editing-comment.gif b/static/figures/dev/reviewer-workflow/gif-editing-comment.gif new file mode 100644 index 000000000..1dd31b0ef Binary files /dev/null and b/static/figures/dev/reviewer-workflow/gif-editing-comment.gif differ diff --git a/static/figures/dev/reviewer-workflow/gif-multi-line-comment.gif b/static/figures/dev/reviewer-workflow/gif-multi-line-comment.gif new file mode 100644 index 000000000..f1651a0f8 Binary files /dev/null and b/static/figures/dev/reviewer-workflow/gif-multi-line-comment.gif differ diff --git a/static/figures/dev/reviewer-workflow/gif-resolving-comment.gif b/static/figures/dev/reviewer-workflow/gif-resolving-comment.gif new file mode 100644 index 000000000..6b6ad2590 Binary files /dev/null and b/static/figures/dev/reviewer-workflow/gif-resolving-comment.gif differ diff --git a/static/figures/dev/reviewer-workflow/gif-split-view.gif b/static/figures/dev/reviewer-workflow/gif-split-view.gif new file mode 100644 index 000000000..b14f7189a Binary files /dev/null and b/static/figures/dev/reviewer-workflow/gif-split-view.gif differ diff --git a/static/figures/dev/reviewer-workflow/gif-submitting-review.gif b/static/figures/dev/reviewer-workflow/gif-submitting-review.gif new file mode 100644 index 000000000..5d52c84ee Binary files /dev/null and b/static/figures/dev/reviewer-workflow/gif-submitting-review.gif differ