Uh oh!
There was an error while loading. Please reload this page.
refactor: Phase 2 Documentation Workflows Consolidation planning - #1306
Conversation
Warning Review limit reached
Next review available in:33 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Repository YAML (base), Organization UI (inherited) Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (8)
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
✅ Template check passed after update. Thanks for fixing the PR description. |
Consolidate documentation validation workflows into single workflow: - Migrate validate-mermaid-pr.yml logic (mermaid validation job) - Migrate readme-audit.yml logic (README structure validation job) - Use conditional jobs based on file changes - Both jobs run independently, post PR comments with results - Covers syntax, accessibility, colour contrast for mermaid - Covers frontmatter and structure for README Jobs: - validate-mermaid: Checks mermaid diagrams on PR/push - validate-readme: Checks README structure on PR/dispatch Benefits: - Single validation workflow for documentation - Unified error reporting to PRs - Reduced noise in workflow runs - Cleaner triggers and concurrency Refs: Issue #1307, Epic #1227, PR #1306 Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Consolidate documentation maintenance workflows into single workflow: - Migrate readme-regen.yml logic (auto-regen job) - Migrate readme-update.yml logic (manual update job) - Migrate readme-audit.yml logic (scheduled audit job) - Use conditional jobs based on event type and dispatch inputs Jobs: - auto-regen-readme: Triggers on push to develop, regenerates impacted READMEs - manual-update: Triggered via dispatch, updates mermaid/staleness based on input - audit-docs: Scheduled weekly (Mon 9 AM UTC) + manual dispatch, comprehensive audit Supports: - Push-triggered automatic README regeneration - Manual dispatch for README/Mermaid updates with scope options - Scheduled weekly documentation audit - Manual audit trigger via dispatch - Critical findings issue creation on scheduled failures Benefits: - All maintenance tasks in single workflow - Scheduled audit prevents documentation drift - Manual maintenance easily accessible - Clear separation of concerns with conditional jobs Refs: Issue #1308, Epic #1227, PR #1306 Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit:4648e2814d
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| if: contains(github.event.pull_request.title, 'docs') || | ||
| contains(github.event.pull_request.files.*.filename, '.md') |
There was a problem hiding this comment.
For PRs whose title does not contain docs, github.event.pull_request.files is not present in the pull-request webhook payload, so the Mermaid condition evaluates false and the README job always skips; both also skip under the promised manual-dispatch trigger because no pull_request object exists. The current .github/workflows/validate-mermaid-pr.yml:46-89 deliberately derives changed files with git diff; retain that approach or query the API rather than silently removing the blocking syntax, accessibility, and contrast checks.
AGENTS.md reference: AGENTS.md:L22-L22
Useful? React with 👍 / 👎.
| - Copy all steps from `readme-audit.yml` | ||
| - Add condition: `github.event_name == 'schedule' || (github.event_name == 'workflow_dispatch' && github.event.inputs.action == 'audit')` | ||
| - Configure schedule: Weekly (e.g., Monday 9 AM UTC) |
There was a problem hiding this comment.
When the weekly schedule event fires, it supplies neither inputs.scope nor inputs.output_format. The steps being copied from .github/workflows/readme-audit.yml:51-54 pass both values directly as required CLI arguments, so the scheduled audit will receive empty values instead of a valid scope and format. Define schedule-safe defaults such as all and markdown before adding this trigger.
Useful? React with 👍 / 👎.
| - Copy all steps from `readme-update.yml` | ||
| - Add condition: `github.event_name == 'workflow_dispatch' && github.event.inputs.action == 'update'` | ||
| - Add input parameter for update scope (readme, mermaid, both) | ||
| - Execute selected update logic |
There was a problem hiding this comment.
If the manual-update steps are copied as instructed, the new readme and both values are incompatible with .github/workflows/readme-update.yml:65-77, whose conditions recognise only all, mermaid, and staleness. Selecting both or readme would therefore skip both update operations while the workflow could still complete successfully; retain the existing values or explicitly map the new choices to the copied conditions.
Useful? React with 👍 / 👎.
| regen-readme: | ||
| if: github.event_name == 'push' && github.ref == 'refs/heads/develop' |
There was a problem hiding this comment.
Restricting regen-readme to pushes drops the existing pull-request path in .github/workflows/readme-regen.yml:4-13, including the dry-run execution at lines 95-96. Once the legacy workflow is deleted, generator failures in documentation PRs will not be exercised until after merge when the develop push runs; include pull_request and preserve the dry-run branch rather than testing only the push path.
Useful? React with 👍 / 👎.
| 1. **Disable Old Workflows** (in this order) | ||
| - Add `if: false` to top-level condition in: |
There was a problem hiding this comment.
GitHub Actions does not support a workflow-level if; conditions are valid only on jobs and steps. Following this instruction makes all four legacy files invalid workflows rather than valid but inactive workflows, undermining the proposed 24–48-hour monitoring stage. Put if: false on every job or temporarily restrict each workflow's on triggers instead.
Useful? React with 👍 / 👎.
⏱️ Aging and SLA annotation
Maintained by project-meta-sync workflow. |
ashleyshaw
commented
Jul 24, 2026
PHASE_2_EXECUTION.md line 102: Updated job condition to use 🤖 Addressed by Claude Code |
ashleyshaw
commented
Jul 24, 2026
PHASE_2_ISSUES.md line 127: Updated "Scheduled Audit Job" to explicitly define default values for 🤖 Addressed by Claude Code |
ashleyshaw
commented
Jul 24, 2026
PHASE_2_ISSUES.md line 121: Updated "Manual Update Job" to preserve existing update-scope values 🤖 Addressed by Claude Code |
ashleyshaw
commented
Jul 24, 2026
PHASE_2_EXECUTION.md line 146: Updated "regen-readme" job condition to preserve both 🤖 Addressed by Claude Code |
ashleyshaw
commented
Jul 24, 2026
PHASE_2_EXECUTION.md line 256: Updated deprecation approach — GitHub Actions does not support workflow-level 🤖 Addressed by Claude Code |
📄 README Validation❌ One or more README checks failed.
|
🎨 Mermaid Diagram Validation❌ One or more Mermaid diagram checks failed.
|
🔍 Reviewer Summary for PR #1306CI Status: ❌ Recommendations
|
- Create detailed Phase 2 execution plan (12-16 hours) - Document 4 workflows to consolidate into 2 new workflows - Design docs-validation.yml (mermaid + readme validation) - Design docs-maintenance.yml (auto-regen + audit + manual update) - Provide integration testing checklist - Define rollback and success criteria - Create GitHub issue templates for Phase 2 work items - Timeline: weeks 5-8 - Expected savings: ~40 GHA minutes/week Phase 2 consolidates: - validate-mermaid-pr.yml - readme-regen.yml - readme-update.yml - readme-audit.yml Into: - docs-validation.yml (PR validation) - docs-maintenance.yml (maintenance + audit) Refs: Epic #1227 Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Consolidate documentation validation workflows into single workflow: - Migrate validate-mermaid-pr.yml logic (mermaid validation job) - Migrate readme-audit.yml logic (README structure validation job) - Use conditional jobs based on file changes - Both jobs run independently, post PR comments with results - Covers syntax, accessibility, colour contrast for mermaid - Covers frontmatter and structure for README Jobs: - validate-mermaid: Checks mermaid diagrams on PR/push - validate-readme: Checks README structure on PR/dispatch Benefits: - Single validation workflow for documentation - Unified error reporting to PRs - Reduced noise in workflow runs - Cleaner triggers and concurrency Refs: Issue #1307, Epic #1227, PR #1306 Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Consolidate documentation maintenance workflows into single workflow: - Migrate readme-regen.yml logic (auto-regen job) - Migrate readme-update.yml logic (manual update job) - Migrate readme-audit.yml logic (scheduled audit job) - Use conditional jobs based on event type and dispatch inputs Jobs: - auto-regen-readme: Triggers on push to develop, regenerates impacted READMEs - manual-update: Triggered via dispatch, updates mermaid/staleness based on input - audit-docs: Scheduled weekly (Mon 9 AM UTC) + manual dispatch, comprehensive audit Supports: - Push-triggered automatic README regeneration - Manual dispatch for README/Mermaid updates with scope options - Scheduled weekly documentation audit - Manual audit trigger via dispatch - Critical findings issue creation on scheduled failures Benefits: - All maintenance tasks in single workflow - Scheduled audit prevents documentation drift - Manual maintenance easily accessible - Clear separation of concerns with conditional jobs Refs: Issue #1308, Epic #1227, PR #1306 Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Disable 4 legacy workflows consolidated into docs-validation.yml and docs-maintenance.yml: - validate-mermaid-pr.yml → docs-validation.yml (validate-mermaid job) - readme-regen.yml → docs-maintenance.yml (auto-regen-readme job) - readme-update.yml → docs-maintenance.yml (manual-update job) - readme-audit.yml → docs-validation.yml + docs-maintenance.yml (jobs split) Disable strategy: - Change trigger to empty workflow_run (no triggers) - Add [DEPRECATED] to workflow name - Add comment explaining consolidation - Workflows remain in git history for rollback if needed Monitoring period: 24-48 hours Will delete after no issues reported Refs: Issue #1309 (Testing), Issue #1310 (Cleanup), Epic #1227 Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
- PHASE_2_EXECUTION.md line 102: Preserve git diff approach for changed file detection (P1) - PHASE_2_EXECUTION.md line 146: Preserve pull_request trigger for README regeneration - PHASE_2_EXECUTION.md line 256: Use job-level `if: false` instead of workflow-level - PHASE_2_ISSUES.md line 121: Preserve existing update-scope values (all, mermaid, staleness) - PHASE_2_ISSUES.md line 127: Supply defaults for scheduled audit inputs Addresses all 5 Codex inline review comments with implementation details. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
5f7b2b4 to
4852496CompareUh oh!
There was an error while loading. Please reload this page.
Linked issues
Relates to #1227, #1307, #1308, #1309, #1310, #1311
Summary
Phase 2: Documentation Workflows Consolidation — Complete implementation of the second phase of the GitHub Workflows Consolidation Initiative.
This PR implements Phase 2 of 4, consolidating 4 documentation-related workflows into 2 streamlined workflows, reducing complexity, duplication, and maintenance burden.
Consolidation Overview:
New Workflows:
docs-validation.yml— Consolidated PR validation (Mermaid + README validation)docs-maintenance.yml— Consolidated maintenance tasks (auto-regen, manual updates, audits)Safety Nets
Existing tests covering behaviour:
New/refined tests added:
Static analysis/lint rules touched:
Approach
Structural changes (APIs, patterns):
Dead code removed? Yes
Metrics / Benchmarks
Verification
Risk & Rollback
if: falseconditionsif: falseto re-enableChangelog
Added
docs-validation.ymlfor PR-based documentation validationdocs-maintenance.ymlfor scheduled and manual maintenancePHASE_2_EXECUTION.md,PHASE_2_ISSUES.mdChanged
Removed
Checklist (Global DoD / PR)