docs: codify PR review workflow (CodeRabbit gate)

[flyingrobots]

Codifies the expected submission workflow: branch+PR, wait for CodeRabbitAI, extract/bucket review comments, iterate until approval, then merge. Also documents the no-direct-to-main and no-admin-bypass expectations.

[coderabbitai]

Summary by CodeRabbit

• Documentation
  • Added a comprehensive PR submission and review workflow guide enforcing CI green, review approval, and a repeatable review loop.
  • Added a guide for extracting and organizing actionable feedback from PR reviews.
  • Improved the comment-extraction documentation to make title extraction more robust and provide clearer examples.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

Walkthrough

Adds two new procedure documents and updates the docs index: a PR submission + CodeRabbitAI review workflow and a procedure for extracting and categorizing CodeRabbitAI PR comments; one procedure includes a small change to example JSON title-extraction logic.

Changes

Cohort / File(s)	Summary
Documentation index docs/INDEX.md	Inserts two new entries under Reports/Procedures/TeX pipeline pointing to the new procedure docs.
New procedure documents docs/procedures/PR-WORKFLOW.md, docs/procedures/EXTRACT-PR-COMMENTS.md	Adds PR-WORKFLOW.md (end-to-end PR submission and non-bypassable review loop, Steps 0–6) and EXTRACT-PR-COMMENTS.md (workflow for parsing CodeRabbitAI comments and priority buckets). EXTRACT-PR-COMMENTS.md updates example JSON extraction to use a safe fallback for the title (third line if present, otherwise "UNTITLED") and strips asterisks.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

✨ New rules, new paths, a tidy scroll,
PRs march forward, checks keep control.
Comments sorted, titles guarded tight—
Merge on green, and everything's right. 🛠️

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change—documenting and codifying the PR review workflow with CodeRabbit as a required gate.
Description check	✅ Passed	The description directly relates to the changeset, clearly outlining the submission workflow and no-bypass expectations that the new documentation enforces.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch docs/pr-review-workflow

---

📜 Recent review details

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 7793a4a and 8492ee9.

📒 Files selected for processing (3)

• docs/INDEX.md
• docs/procedures/EXTRACT-PR-COMMENTS.md
• docs/procedures/PR-WORKFLOW.md

🧰 Additional context used

📓 Path-based instructions (1)

{README*,**/*API*,**/*.md}

📄 CodeRabbit inference engine (AGENTS.md)

Update READMEs, API documentation, and internal documentation to reflect new code changes

Files:

• docs/procedures/EXTRACT-PR-COMMENTS.md
• docs/INDEX.md
• docs/procedures/PR-WORKFLOW.md

🧠 Learnings (4)

📓 Common learnings

Learnt from: CR
Repo: flyingrobots/loom PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-28T23:40:05.843Z
Learning: Open a Pull Request targeting the `main` branch with a description that includes Summary of Changes, Link to Task, and How to Verify

Learnt from: CR
Repo: flyingrobots/loom PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-28T23:40:05.843Z
Learning: Applies to {README*,**/*API*,**/*.md} : Update READMEs, API documentation, and internal documentation to reflect new code changes

📚 Learning: 2025-12-28T23:40:05.843Z

Learnt from: CR
Repo: flyingrobots/loom PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-28T23:40:05.843Z
Learning: Applies to {README*,**/*API*,**/*.md} : Update READMEs, API documentation, and internal documentation to reflect new code changes

Applied to files:

• docs/procedures/EXTRACT-PR-COMMENTS.md
• docs/INDEX.md
• docs/procedures/PR-WORKFLOW.md

📚 Learning: 2025-12-28T23:40:05.843Z

Learnt from: CR
Repo: flyingrobots/loom PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-28T23:40:05.843Z
Learning: Applies to .github/workflows/*.{yml,yaml} : Review and update GitHub Actions workflows in `.github/workflows/` to integrate new test cases and determine if tests should run on every Push or PR

Applied to files:

• docs/procedures/EXTRACT-PR-COMMENTS.md
• docs/procedures/PR-WORKFLOW.md

📚 Learning: 2025-12-28T23:40:05.843Z

Learnt from: CR
Repo: flyingrobots/loom PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-28T23:40:05.843Z
Learning: Open a Pull Request targeting the `main` branch with a description that includes Summary of Changes, Link to Task, and How to Verify

Applied to files:

• docs/procedures/PR-WORKFLOW.md

🪛 LanguageTool

docs/procedures/EXTRACT-PR-COMMENTS.md

[style] ~16-~16: Consider using a different verb for a more formal wording.
Context: ...** using this document. 6. Bucket and fix issues (commit early/often; push upda...

(FIX_RESOLVE)

🔇 Additional comments (11)

docs/INDEX.md (1)

83-84: LGTM — index entries are well-positioned and accurately describe the new procedures.

The new references are concise, descriptive, and properly integrated into the Reports/Procedures section. Both links are correct and the descriptions accurately reflect the document contents.

docs/procedures/EXTRACT-PR-COMMENTS.md (2)

28-32: Previous merge-readiness ambiguity has been successfully resolved.

The reformatted conditions now clearly establish three sequential gates (all required):

1. CI checks green
2. CodeRabbitAI satisfied (approve OR no unresolved feedback)
3. Human approval (if required by policy)

This eliminates the logical confusion from earlier drafts. Structure is clear and unambiguous.

---

138-138: Title extraction jq logic is production-ready; bash workflow verified executable with zero unresolved variables.

Line 138's pattern (.body | split("\n")[2:3][0] // "UNTITLED" | gsub("\\*\\*"; "")) handles edge cases correctly—slicing to index 2, null-coalescing to fallback, stripping markdown. The complete example workflow (lines 255–307) passes bash syntax validation with all variables properly substituted (PR_NUMBER, OWNER, REPO, LATEST_COMMIT, and jq-scoped variables). No unresolved placeholders. Script executes cleanly with the provided PR data.

docs/procedures/PR-WORKFLOW.md (8)

32-32: Grammar correction has been applied — "bug fixes" (two-word form) is now correctly used.

Line 32 now properly uses the modern standard form "bug fixes" instead of the single-word "bugfixes". This aligns with AP, Chicago, and Google style guides and maintains consistency with professional documentation standards.

---

3-11: Purpose statement is clear and appropriately operational.

The purpose cleanly distills the workflow intent: single submission path via PRs, systematic feedback handling, approval-gated merges. The note about "operational" and "without interpretation drift" signals appropriate procedural rigor.

---

15-21: Rules section is unambiguous and properly non-negotiable.

Four explicit, unqualified rules establish the boundaries:

1. No direct-to-main commits
2. No admin bypass merges (even with admin privileges)
3. CI green ≠ merge-ready (review is separate gate)
4. Small, frequent commits preferred

The rule set correctly prevents the exact workflow violations being codified against. Tone is appropriately firm.

---

46-54: Step 2 correctly emphasizes waiting for automated review before proceeding.

Line 54's guidance — "Do not merge 'because it looks fine'" — directly counteracts the risk of developers merging prematurely. The explicit "Do not assume approval based on manual code inspection" is operationally sound.

---

64-83: Step 4 batching strategy (P0→P1→P2→P3) is well-prioritized and executable.

The four-tier bucketing aligns feedback extraction procedure with remediation workflow:

• P0: correctness/determinism/security (highest risk)
• P1: major design/API drift (high impact)
• P2: minor issues/maintainability (low impact)
• P3: nits (lowest impact)

Batching reduces cognitive load and enables parallel discussion (e.g., "We're addressing P0 first, P1 feedback is noted").

---

85-93: Deterministic resolution markers are a strong procedural addition.

The guidance to use ✅ Addressed in commit <sha> in review replies directly reduces the pain of extracting actionable comments in subsequent review rounds. This is both operationally sound and reduces toil.

---

95-103: Merge-readiness gate and auto-merge fallback are properly handled.

Step 6 correctly requires approval before merge and provides auto-merge option for branch protection scenarios. The conditional language ("If branch protection requires it") acknowledges varying repository configurations while maintaining the non-bypass principle.

---

107-110: Agent/automation notes appropriately address non-human contributors.

The guidance to "behave like a non-admin contributor" and treat admin privileges as "break glass" is operationally sound and establishes behavioral expectations for CI/CD agents or automation tools. This prevents unintended policy bypass.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)

docs/procedures/EXTRACT-PR-COMMENTS.md (1)

116-147: Add defensive handling for title extraction in Step 6.

Line 138 assumes comments always have a newline-separated structure with the title at index [2]. If a comment body is malformed or has fewer lines, jq silently returns null or the wrong content.

Add a fallback to prevent silent failures:

🔎 Proposed improvement

   title: (
-    (.body | split("\n")[2] | gsub("\\*\\*"; ""))
+    (.body | split("\n")[2:3][0] // "UNTITLED" | gsub("\\*\\*"; ""))
   ),

This uses jq's // "UNTITLED" fallback operator to ensure title is never null, making downstream processing more resilient.

docs/INDEX.md (1)

79-85: Add brief descriptive context to new procedure entries for consistency.

Lines 83–84 introduce new procedure entries but lack the descriptive text present in other sections (e.g., "Canonical encoding", "ADRs are the 'why' trail", etc.). Add one-line summaries to match the index's established pattern and improve discoverability.

🔎 Proposed improvement

 ## Reports / procedures / TeX pipeline

 - reports: `docs/REPORTS/`
 - procedures: `docs/procedures/`
-- PR submission + review loop: `docs/procedures/PR-WORKFLOW.md`
-- CodeRabbitAI comment extraction: `docs/procedures/EXTRACT-PR-COMMENTS.md`
+- **PR submission + review loop:** Codified submission workflow requiring branch → PR → CI → CodeRabbitAI review → approval → merge. See `docs/procedures/PR-WORKFLOW.md`.
+- **CodeRabbitAI comment extraction:** Procedure for identifying actionable (vs. stale/already-fixed) comments from CodeRabbitAI PR reviews. Includes bucketing by priority (P0–P3). See `docs/procedures/EXTRACT-PR-COMMENTS.md`.
 - PDF build: `docs/tex/build-pdf.sh`

📜 Review details

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 1651c3a and 7793a4a.

📒 Files selected for processing (3)

• docs/INDEX.md
• docs/procedures/EXTRACT-PR-COMMENTS.md
• docs/procedures/PR-WORKFLOW.md

🧰 Additional context used

📓 Path-based instructions (1)

{README*,**/*API*,**/*.md}

📄 CodeRabbit inference engine (AGENTS.md)

Update READMEs, API documentation, and internal documentation to reflect new code changes

Files:

• docs/procedures/PR-WORKFLOW.md
• docs/INDEX.md
• docs/procedures/EXTRACT-PR-COMMENTS.md

🧠 Learnings (4)

📓 Common learnings

Learnt from: CR
Repo: flyingrobots/loom PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-28T23:40:05.843Z
Learning: Open a Pull Request targeting the `main` branch with a description that includes Summary of Changes, Link to Task, and How to Verify

Learnt from: CR
Repo: flyingrobots/loom PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-28T23:40:05.843Z
Learning: Applies to {README*,**/*API*,**/*.md} : Update READMEs, API documentation, and internal documentation to reflect new code changes

📚 Learning: 2025-12-28T23:40:05.843Z

Learnt from: CR
Repo: flyingrobots/loom PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-28T23:40:05.843Z
Learning: Applies to {README*,**/*API*,**/*.md} : Update READMEs, API documentation, and internal documentation to reflect new code changes

Applied to files:

• docs/procedures/PR-WORKFLOW.md
• docs/INDEX.md
• docs/procedures/EXTRACT-PR-COMMENTS.md

📚 Learning: 2025-12-28T23:40:05.843Z

Learnt from: CR
Repo: flyingrobots/loom PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-28T23:40:05.843Z
Learning: Applies to .github/workflows/*.{yml,yaml} : Review and update GitHub Actions workflows in `.github/workflows/` to integrate new test cases and determine if tests should run on every Push or PR

Applied to files:

• docs/procedures/PR-WORKFLOW.md
• docs/procedures/EXTRACT-PR-COMMENTS.md

📚 Learning: 2025-12-28T23:40:05.843Z

Learnt from: CR
Repo: flyingrobots/loom PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-28T23:40:05.843Z
Learning: Open a Pull Request targeting the `main` branch with a description that includes Summary of Changes, Link to Task, and How to Verify

Applied to files:

• docs/procedures/PR-WORKFLOW.md

🪛 LanguageTool

docs/procedures/PR-WORKFLOW.md

[grammar] ~32-~32: Ensure spelling is correct
Context: ...feat/... for features - fix/... for bugfixes - chore/... for tooling/maintenance ```bash git che...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

docs/procedures/EXTRACT-PR-COMMENTS.md

[style] ~16-~16: Consider using a different verb for a more formal wording.
Context: ...** using this document. 6. Bucket and fix issues (commit early/often; push upda...

(FIX_RESOLVE)

[flyingrobots]

CodeRabbitAI feedback extracted + addressed.

✅ Addressed in commit 8492ee9:

• Clarified merge-readiness gate logic in docs/procedures/EXTRACT-PR-COMMENTS.md
• Made jq title extraction defensive (fallback "UNTITLED")
• Added descriptive context in docs/INDEX.md for new procedure entries
• Updated branch naming wording to "bug fixes" in docs/procedures/PR-WORKFLOW.md

Batch report: /tmp/batch-14-coderabbit-issues.md

[flyingrobots]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.