Skip to content

Commit e56aae0

Browse files
AdamGohsAdamGohs
authored
Merge pull request #107 from USACE-RMC/feature/review-workflow-infrastructure
Add review workflow infrastructure
2 parents fd1c4aa + 0dc339a commit e56aae0

14 files changed

Lines changed: 1862 additions & 20 deletions

File tree

‎.claude/skills/new-revision/SKILL.md‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
---
2+
name: new-revision
3+
description: Scaffold a new revision of an existing document by copying the latest version folder to a new version, setting the draft flag, and creating an appropriately-prefixed git branch for the review process.
4+
---
5+
6+
# New Revision
7+
8+
Scaffold a new revision of an existing document on the RMC documentation site. Copies the latest version folder to a new version directory, marks the document as draft, and creates a `docs/major/` or `docs/minor/` branch ready for the review workflow.
9+
10+
**Arguments:** `$ARGUMENTS` — optional. If provided, use as hints for the prompts below (e.g., a document path or version number). Still confirm each value with the user before proceeding.
11+
12+
## Step 1: Gather Information via Interactive Prompts
13+
14+
Prompt the user for each value, one at a time. Show sensible defaults where possible. Do NOT proceed until all values are confirmed.
15+
16+
### 1a — Document selection
17+
18+
Ask: "Which existing document are you revising?"
19+
20+
Read [static/versions/latestVersions.json](static/versions/latestVersions.json) and present the keys as a numbered list. The user picks one. The selected key is the `docBasePath` (e.g., `desktop-applications/lifesim/users-guide`).
21+
22+
The corresponding value in the JSON is the `currentVersion` (e.g., `v1.0`).
23+
24+
### 1b — Revision type
25+
26+
Ask: "Is this a major revision or a minor revision?"
27+
28+
- **Major revision** — substantial changes warranting a new major version. Branch prefix: `docs/major/`. Goes through Lane 2 (Peer → Lead Civil review).
29+
- **Minor revision** — smaller updates warranting a minor version bump. Branch prefix: `docs/minor/`. Goes through Lane 3 (Peer review only).
30+
31+
### 1c — New version number
32+
33+
Compute the default based on revision type:
34+
- Major: increment the major component, reset minor to 0 (e.g., `v1.0` → `v2.0`, `v1.5` → `v2.0`).
35+
- Minor: increment the minor component (e.g., `v1.0` → `v1.1`, `v1.5` → `v1.6`).
36+
37+
Ask: "The new version will be `{newVersion}`. Is that correct, or would you like a different version number?"
38+
39+
### 1d — Branch name
40+
41+
Compute the default branch name as `docs/{major|minor}/{slug}-{newVersionWithoutV}` where `{slug}` is the last segment of the docBasePath (e.g., `users-guide`). Example: `docs/major/users-guide-v2.0`.
42+
43+
Ask: "I'll use branch name `{branchName}`. Is that correct, or would you like a different name?"
44+
45+
### 1e — Confirmation
46+
47+
Display a summary:
48+
49+
```
50+
Document: {docBasePath}
51+
Current version: {currentVersion}
52+
New version: {newVersion}
53+
Revision type: {major|minor}
54+
Branch: {branchName}
55+
Source folder: docs/{docBasePath}/{currentVersion}/
56+
Target folder: docs/{docBasePath}/{newVersion}/
57+
Figures source: static/figures/{docBasePath}/{currentVersion}/
58+
Figures target: static/figures/{docBasePath}/{newVersion}/
59+
Bibliography: static/bibliographies/{docBasePath}/{newVersion}/bib.json
60+
```
61+
62+
Ask: "Does this look correct? (yes/no)"
63+
64+
If no, ask which value to change and loop back.
65+
66+
## Step 2: Create the git branch
67+
68+
Create and check out the branch from the current `main` (not from the user's current branch — start clean):
69+
70+
```bash
71+
git fetch origin main
72+
git checkout -b {branchName} origin/main
73+
```
74+
75+
If the branch already exists, abort and report the conflict to the user.
76+
77+
## Step 3: Copy the version folder
78+
79+
Copy the entire current version directory to the new version directory:
80+
81+
```bash
82+
cp -r docs/{docBasePath}/{currentVersion}/ docs/{docBasePath}/{newVersion}/
83+
```
84+
85+
Then copy the figures folder:
86+
87+
```bash
88+
cp -r static/figures/{docBasePath}/{currentVersion}/ static/figures/{docBasePath}/{newVersion}/
89+
```
90+
91+
Then copy the bibliography folder:
92+
93+
```bash
94+
cp -r static/bibliographies/{docBasePath}/{currentVersion}/ static/bibliographies/{docBasePath}/{newVersion}/
95+
```
96+
97+
If any source folder doesn't exist, skip it and note in the final report.
98+
99+
## Step 4: Update the version history file
100+
101+
Read `docs/{docBasePath}/{newVersion}/00-version-history.mdx` and add a new placeholder row at the top of the `TableVersionHistory` props arrays:
102+
103+
- `versions`: prepend the new version number without the `v` prefix (e.g., `'2.0'`)
104+
- `dates`: prepend the current month and year (e.g., `'April 2026'`)
105+
- `descriptions`: prepend `'Placeholder — describe the changes in this revision.'`
106+
- `modifiedBy`: prepend `'Enter author name'`
107+
- `reviewedBy`: prepend `'-'`
108+
- `approvedBy`: prepend `'-'`
109+
110+
The author will fill in the actual values during the PR. The site admin will fill in `reviewedBy`/`approvedBy` at merge time.
111+
112+
## Step 5: Set the draft flag
113+
114+
Find the document's entry in the appropriate landing page JS file (search `src/pages/` for the `doc_location` matching `{docBasePath}`). Common locations:
115+
116+
- Desktop apps: `src/pages/desktop-applications/{software}.js`
117+
- Toolboxes: `src/pages/toolboxes/{suite}.js`
118+
- Web apps: `src/pages/web-applications/{software}.js`
119+
- Dev: `src/pages/dev.js`
120+
121+
In the matching entry, change `draft: false` to `draft: true`.
122+
123+
> Note: this flips the draft flag on the *currently published* version too, since the flag is per-document, not per-version. The version-aware watermark logic in [src/theme/DocItem/index.js](src/theme/DocItem/index.js) ensures the watermark only appears on the *latest* version of a flagged document. Until this PR is merged, the latest version on the live site is still the previous version, which will not be watermarked. Once merged, the new version becomes latest and (briefly, until the site admin flips the flag back to `false`) the watermark will appear on it.
124+
125+
## Step 6: Run generation scripts
126+
127+
Run the build generation scripts to pick up the new version:
128+
129+
```bash
130+
npm run sidebars && npm run counters && npm run versions
131+
```
132+
133+
Verify no errors. If errors occur, diagnose and fix.
134+
135+
## Step 7: Verify and report
136+
137+
1. Glob to confirm the new version folder exists at `docs/{docBasePath}/{newVersion}/`
138+
2. Confirm the version history file has the new row
139+
3. Confirm the landing page JS has `draft: true`
140+
4. Confirm the branch is checked out (`git branch --show-current`)
141+
5. Report a summary to the user:
142+
143+
```
144+
New revision scaffolded successfully!
145+
146+
Document: {docBasePath}
147+
Old version: {currentVersion}
148+
New version: {newVersion}
149+
Branch: {branchName}
150+
151+
Created:
152+
- docs/{docBasePath}/{newVersion}/ (copied from {currentVersion})
153+
- static/figures/{docBasePath}/{newVersion}/ (copied)
154+
- static/bibliographies/{docBasePath}/{newVersion}/ (copied)
155+
156+
Modified:
157+
- docs/{docBasePath}/{newVersion}/00-version-history.mdx (new placeholder row)
158+
- {landing page JS file} (draft: true)
159+
160+
Next steps:
161+
1. Edit the new version's MDX files to make your changes
162+
2. Update 00-version-history.mdx with a real description and your name
163+
3. Run `npm start` to preview locally
164+
4. When ready, commit and open a PR (the workflow will detect the branch prefix and start {Lane 2: Peer → Lead Civil | Lane 3: Peer review} automatically)
165+
```

‎.claude/skills/pr/SKILL.md‎

Lines changed: 29 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -68,28 +68,46 @@ Read `.claude/skills/git-conventions.md` for PR conventions.
6868
- Derived from the **overall purpose** of all commits on the branch, not just the latest commit
6969
- Example: "Redesign homepage with product tile grid layout"
7070

71-
### Body
72-
Use this format — **Summary section only, no Test plan**:
71+
### Body — choose the format based on the branch prefix
7372

74-
```markdown
75-
## Summary
76-
- {1-3 bullet points describing the changes and their purpose}
77-
```
73+
**If the current branch starts with `docs/`** → use the **Template Style** (Step 5a). The repo's PR template at `.github/pull_request_template.md` contains a checklist for document authors, including the Lane 1 "Technical edit comments addressed" checkbox that the stage-progression workflow watches for. Passing `--body` to `gh pr create` overrides the template entirely, so the skill must reproduce the template structure with the auto-generated content filled in.
7874

79-
**Do NOT include:**
75+
**Otherwise (infrastructure, tooling, dependency, or any non-doc branch)** → use the **Summary Style** (Step 5b). These PRs are silently ignored by the review workflow and don't need the doc-author checklist.
76+
77+
In both styles, the summary content should be based on **ALL** commits on the branch, not just the most recent one. Read through all the commit messages and the diff to understand the full scope. If `$ARGUMENTS` was provided, use it to focus the title and description.
78+
79+
**Do NOT include in either style:**
8080
- A "Test plan" section
8181
- Any AI attribution, "Generated with Claude", or "Co-Authored-By" lines
8282

83-
If `$ARGUMENTS` was provided, use it to focus the title and description.
83+
### Step 5a: Template Style (for `docs/` branches)
84+
85+
1. Read [.github/pull_request_template.md](.github/pull_request_template.md). Use it as the structural skeleton.
86+
2. Compute the auto-generated summary: 1–3 bullets describing the changes.
87+
3. Compute the list of affected MDX documents: from `git diff --name-only main...HEAD`, keep entries matching `docs/**/*.mdx`. If the base is not `main`, use that instead.
88+
4. Build the PR body by transforming the template:
89+
- Under `## Description`, replace the `<!-- Briefly describe what this PR does and why. -->` comment with the summary bullets.
90+
- Under `## Affected documents`, replace the bare `- ` line with the list of affected MDX files. Format each as a markdown link relative to the repo root: `- [filename.mdx](docs/full/path/filename.mdx)`. If there are no changed MDX files, write `- _No MDX files changed in this PR._`
91+
- Leave the `## Related issue(s)` section's comment placeholder unchanged so the author can fill it in.
92+
- Leave **all checklist items unchecked**, including the Lane 1 Technical edit checkbox. The author checks them as they complete each item; the workflow specifically depends on the Technical edit checkbox being present and unchecked at PR open time.
93+
- Leave the `## Notes for reviewers` comment placeholder unchanged.
94+
95+
The result should be a complete copy of the template with the Description and Affected documents sections populated.
8496

85-
The summary should be based on ALL commits on the branch, not just the most recent one. Read through all the commit messages and the diff to understand the full scope.
97+
### Step 5b: Summary Style (for non-`docs/` branches)
98+
99+
Use this format — **Summary section only, no Test plan**:
100+
101+
```markdown
102+
## Summary
103+
- {1-3 bullet points describing the changes and their purpose}
104+
```
86105

87106
## Step 6: Create the PR
88107

89108
```bash
90109
gh pr create --title "{title}" --body "$(cat <<'EOF'
91-
## Summary
92-
{bullets}
110+
{body from Step 5a or Step 5b}
93111
EOF
94112
)"
95113
```

‎.claude/skills/technical-edit/SKILL.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
name: technical-edit
3+
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.
4+
---
5+
6+
# Technical Edit
7+
8+
Run an AI-assisted technical edit on the current PR's documentation files.
9+
10+
**Arguments:** `$ARGUMENTS` — optional PR number. If omitted, infer from the current branch.
11+
12+
## Step 1: Identify the PR and changed files
13+
14+
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$'`.
15+
16+
## Step 2: Read the review prompt
17+
18+
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.
19+
20+
## Step 3: Review each file
21+
22+
For each changed MDX file:
23+
1. Read the file contents
24+
2. Apply the review prompt to the file
25+
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
26+
27+
## Step 4: Post the review on the PR
28+
29+
Use the GitHub CLI to submit a bundled PR review with inline comments:
30+
31+
```bash
32+
gh api repos/:owner/:repo/pulls/:pr/reviews \
33+
--method POST \
34+
-f body="AI technical edit complete. $(N) comments across $(M) files. Review prompt version: $(VERSION)." \
35+
-f event="COMMENT" \
36+
-f comments="[{\"path\": \"...\", \"line\": N, \"body\": \"...\"}]"
37+
```
38+
39+
Each comment should be formatted as:
40+
```
41+
**[severity]** issue description
42+
43+
> Suggested fix (if applicable)
44+
```
45+
46+
Where severity is one of: 🔴 Must fix, 🟡 Should fix, 🔵 Suggestion.
47+
48+
## Step 5: Report
49+
50+
Tell the user:
51+
- How many comments were posted
52+
- How many files were reviewed
53+
- Which review prompt version was used
54+
- Remind the author to check the "Technical edit comments addressed" checkbox in the PR description when they're done addressing comments

‎.github/CODEOWNERS‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
/.github/ @usace-rmc/docs-admin
2+
/docusaurus.config.js @usace-rmc/docs-admin
3+
/tailwind.config.js @usace-rmc/docs-admin
4+
/package.json @usace-rmc/docs-admin
5+
/package-lock.json @usace-rmc/docs-admin
6+
/scripts/ @usace-rmc/docs-admin
7+
/src/theme/ @usace-rmc/docs-admin
8+
/src/pages/ @usace-rmc/docs-admin
9+
/src/components/ @usace-rmc/docs-admin
10+
/src/contexts/ @usace-rmc/docs-admin
11+
/src/clientModules/ @usace-rmc/docs-admin
12+
/src/css/ @usace-rmc/docs-admin
13+
/src/draftDocs.js @usace-rmc/docs-admin

‎.github/ai-review/technical-editor-prompt.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# RMC Technical Editor Review Prompt
2+
3+
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.
4+
5+
## Audience
6+
7+
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.
8+
9+
## Review criteria
10+
11+
### Grammar and mechanics
12+
- Spelling, punctuation, and sentence structure
13+
- Subject-verb agreement
14+
- Correct use of hyphens, em dashes, and en dashes
15+
- Consistent serial comma usage
16+
17+
### Tense and voice
18+
- Prefer third-person active voice for procedures and descriptions
19+
- Flag passive voice when active would be clearer
20+
- Flag inconsistent tense within a section
21+
22+
### Clarity and concision
23+
- Flag wordy passages that could be shortened without losing meaning
24+
- Flag ambiguous pronouns or unclear referents
25+
- Flag sentences over 40 words that could be split
26+
- Flag buried leads — key information at the end of a long sentence
27+
28+
### Terminology consistency
29+
- Flag inconsistent use of terms within the document (e.g., alternating between "embankment" and "dam" when referring to the same structure)
30+
- Do NOT flag correct domain terminology as errors
31+
32+
### Section 508 accessibility compliance
33+
- Every image must have alt text (check for `alt=` attribute)
34+
- Heading hierarchy must not skip levels (e.g., h2 followed by h4 without h3)
35+
- Link text must be descriptive (flag "click here" or "link" as link text)
36+
- Tables must have header rows
37+
- Lists must use proper markdown list syntax, not manual numbering with plain text
38+
- Color must not be the sole means of conveying information
39+
40+
### Style consistency
41+
- Figure and table captions must follow a consistent format
42+
- Citations must use the site's citation key format
43+
- Units should be consistent within each document (metric or imperial, not mixed)
44+
- Acronyms must be defined on first use within each chapter
45+
46+
## Output format
47+
48+
For each finding, produce:
49+
- The file path and line number(s)
50+
- A severity level: 🔴 Must fix (errors, accessibility violations), 🟡 Should fix (clarity, consistency issues), 🔵 Suggestion (stylistic improvements)
51+
- A clear description of the issue
52+
- A suggested fix where possible (use GitHub suggestion block format)
53+
54+
## What NOT to flag
55+
- Correct use of technical terminology, even if uncommon
56+
- MDX component syntax (imports, JSX elements)
57+
- Frontmatter fields
58+
- Matters of technical judgment or domain accuracy (that is the peer reviewer's job)
59+
- Alternative phrasings that are equally acceptable

‎.github/pull_request_template.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
## Description
2+
3+
<!-- Briefly describe what this PR does and why. -->
4+
5+
## Affected documents
6+
7+
-
8+
9+
## Related issue(s)
10+
11+
<!-- Link related issues. Use "Closes #N" to auto-close on merge. -->
12+
13+
## Pre-submission checklist
14+
15+
- [ ] I have previewed these changes locally or via the PR preview URL
16+
- [ ] My branch name uses one of the expected prefixes: `docs/new/`, `docs/major/`, `docs/minor/`, or `docs/fix/`
17+
- [ ] I have updated `00-version-history.mdx` if this change warrants a version entry
18+
- [ ] I have assigned a specific peer reviewer via the Reviewers sidebar (if known)
19+
20+
## Technical edit (Lane 1 only)
21+
22+
- [ ] Technical edit comments addressed — ready for Director review
23+
24+
## Notes for reviewers
25+
26+
<!-- Anything reviewers should know. -->

0 commit comments

Comments
 (0)