From 3af0aa6b3084c76ef0b6183452916239cc52dc6d Mon Sep 17 00:00:00 2001 From: Lasmar Khalifa Date: Tue, 26 May 2026 17:05:03 -0400 Subject: [PATCH 1/3] workflow to see docs impact from current branch modifications --- .../maintenance/branch_docs_impact.rb | 64 +++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 internal/workflows/maintenance/branch_docs_impact.rb diff --git a/internal/workflows/maintenance/branch_docs_impact.rb b/internal/workflows/maintenance/branch_docs_impact.rb new file mode 100644 index 00000000..6df05cfb --- /dev/null +++ b/internal/workflows/maintenance/branch_docs_impact.rb @@ -0,0 +1,64 @@ +# typed: true +# frozen_string_literal: true + +#: self as Roast::Workflow + +config do +end + +execute do + cmd(:diff) do + current = %x(git rev-parse --abbrev-ref HEAD).strip + if current == "main" + warn "on main, nothing to compare" + skip! + end + merge_base = %x(git merge-base origin/main HEAD).strip + diff = %x(git diff #{merge_base}) + if diff.strip.empty? + warn "no diff vs origin/main — stage or commit your changes first" + skip! + end + "git diff #{merge_base}" + end + + agent(:analyzer) do + <<~PROMPT + Analyze how the following git diff affects existing documentation. + + DO NOT run git, bash, or any other commands. The diff is the ONLY input. + DO NOT investigate the branch state, untracked files, or commit history. + Work only from the diff below. + + --- DIFF START --- + #{cmd!(:diff).text} + --- DIFF END --- + + For each documentation file in this repo that the diff affects, report: + 1. The doc file path + 2. What in the diff makes it stale + 3. The specific edit needed to bring it back in sync + PROMPT + end + + chat do + <<~PROMPT + Based on the following analysis, summarize the impact of the changes in this branch on the project's documentation. + Highlight any significant improvements or regressions, and provide recommendations for any additional documentation updates that may be necessary. + Do not unecessarily suggest updates if they are not needed. + + Analysis: + #{agent!(:analyzer).response} + PROMPT + end + + agent(:fixer) do + skip! unless arg?(:fix) + <<~PROMPT + Apply the documentation fixes suggested in the analysis below. Edit the + affected files in place. Do not modify any code files; docs only. + + #{agent!(:analyzer).response} + PROMPT + end +end From d2e028dfb9380e1834d520b752c4d42fa829ca62 Mon Sep 17 00:00:00 2001 From: Lasmar Khalifa Date: Tue, 26 May 2026 17:07:07 -0400 Subject: [PATCH 2/3] workflow to see docs impact from current branch modifications --- .../maintenance/branch_docs_impact.rb | 58 +++++++++++++------ 1 file changed, 40 insertions(+), 18 deletions(-) diff --git a/internal/workflows/maintenance/branch_docs_impact.rb b/internal/workflows/maintenance/branch_docs_impact.rb index 6df05cfb..7bcf9cc5 100644 --- a/internal/workflows/maintenance/branch_docs_impact.rb +++ b/internal/workflows/maintenance/branch_docs_impact.rb @@ -4,48 +4,61 @@ #: self as Roast::Workflow config do + agent do + provider :claude + model "claude-opus-4-7" + quiet! + end + chat do + provider :openai + model "gpt-5" + quiet! + end end execute do cmd(:diff) do - current = %x(git rev-parse --abbrev-ref HEAD).strip - if current == "main" - warn "on main, nothing to compare" - skip! - end merge_base = %x(git merge-base origin/main HEAD).strip - diff = %x(git diff #{merge_base}) + diff = %x(git diff --cached #{merge_base}) if diff.strip.empty? - warn "no diff vs origin/main — stage or commit your changes first" + warn "no staged or committed changes vs origin/main" skip! end - "git diff #{merge_base}" + "git diff --cached #{merge_base}" end agent(:analyzer) do <<~PROMPT - Analyze how the following git diff affects existing documentation. + You are checking whether a git diff makes any existing documentation stale. + + Rules: + - Use ONLY the diff below. Do not run any commands. + - Be thorough about finding real issues — do not be conservative. + - But do NOT speculate about docs you cannot see in the diff. + - No markdown headers, no preamble, no caveats, no "limitations" sections. + + Output format — pick exactly one: - DO NOT run git, bash, or any other commands. The diff is the ONLY input. - DO NOT investigate the branch state, untracked files, or commit history. - Work only from the diff below. + If nothing in the diff affects existing docs, output a single line: + No documentation impact. + + Otherwise, output one block per affected doc, separated by blank lines: + + Stale because: + Fix: --- DIFF START --- #{cmd!(:diff).text} --- DIFF END --- - - For each documentation file in this repo that the diff affects, report: - 1. The doc file path - 2. What in the diff makes it stale - 3. The specific edit needed to bring it back in sync PROMPT end - chat do + chat(:report) do <<~PROMPT Based on the following analysis, summarize the impact of the changes in this branch on the project's documentation. Highlight any significant improvements or regressions, and provide recommendations for any additional documentation updates that may be necessary. Do not unecessarily suggest updates if they are not needed. + Do not be verbose. Be super concise. Analysis: #{agent!(:analyzer).response} @@ -61,4 +74,13 @@ #{agent!(:analyzer).response} PROMPT end + + ruby(:output) do + files = cmd!(:diff).text.scan(%r{^diff --git a/\S+ b/(\S+)}).flatten + + puts "Files considered (#{files.size}):" + files.each { |f| puts " #{f}" } + puts agent!(:analyzer).response + puts(agent?(:fixer) ? "Fixes applied." : "(Run with -- fix to apply suggested edits.)") + end end From ee0017361b5561d62ab7a199b929f40844f9fa4a Mon Sep 17 00:00:00 2001 From: Lasmar Khalifa Date: Mon, 1 Jun 2026 17:37:04 -0400 Subject: [PATCH 3/3] Add a workflow for branch impact on docs --- .../maintenance/branch_docs_impact.rb | 37 ++++++++++++------- 1 file changed, 24 insertions(+), 13 deletions(-) diff --git a/internal/workflows/maintenance/branch_docs_impact.rb b/internal/workflows/maintenance/branch_docs_impact.rb index 7bcf9cc5..b351dce8 100644 --- a/internal/workflows/maintenance/branch_docs_impact.rb +++ b/internal/workflows/maintenance/branch_docs_impact.rb @@ -3,6 +3,13 @@ #: self as Roast::Workflow +# Gets the committed diff of the current branch vs origin/main, then analyzes it for potential +# documentation impacts, and optionally applies fixes. This is meant to be run as a pre-merge check, to +# catch any potential documentation issues before they get merged into main. +# +# Accepts a `--fix` flag to apply any suggested fixes in place. Otherwise, it just reports the analysis +# and recommended fixes without applying them. + config do agent do provider :claude @@ -19,15 +26,13 @@ execute do cmd(:diff) do merge_base = %x(git merge-base origin/main HEAD).strip - diff = %x(git diff --cached #{merge_base}) - if diff.strip.empty? - warn "no staged or committed changes vs origin/main" - skip! - end - "git diff --cached #{merge_base}" + fail!("could not determine merge-base with origin/main — run `git fetch origin main` first") if merge_base.empty? + "git diff #{merge_base} HEAD" end agent(:analyzer) do + skip! if cmd!(:diff).text.strip.empty? + fail!("diff too large (#{cmd!(:diff).text.bytesize} bytes) to analyze — narrow the branch or exclude generated files") if cmd!(:diff).text.bytesize > 500_000 <<~PROMPT You are checking whether a git diff makes any existing documentation stale. @@ -54,10 +59,11 @@ end chat(:report) do + skip! if cmd!(:diff).text.strip.empty? <<~PROMPT Based on the following analysis, summarize the impact of the changes in this branch on the project's documentation. Highlight any significant improvements or regressions, and provide recommendations for any additional documentation updates that may be necessary. - Do not unecessarily suggest updates if they are not needed. + Do not suggest updates that are not needed. Do not be verbose. Be super concise. Analysis: @@ -67,6 +73,8 @@ agent(:fixer) do skip! unless arg?(:fix) + skip! if cmd!(:diff).text.strip.empty? + skip! if agent!(:analyzer).response.strip == "No documentation impact." <<~PROMPT Apply the documentation fixes suggested in the analysis below. Edit the affected files in place. Do not modify any code files; docs only. @@ -76,11 +84,14 @@ end ruby(:output) do - files = cmd!(:diff).text.scan(%r{^diff --git a/\S+ b/(\S+)}).flatten - - puts "Files considered (#{files.size}):" - files.each { |f| puts " #{f}" } - puts agent!(:analyzer).response - puts(agent?(:fixer) ? "Fixes applied." : "(Run with -- fix to apply suggested edits.)") + if cmd!(:diff).text.strip.empty? + puts "No changes vs origin/main — nothing to analyze." + else + files = cmd!(:diff).out.scan(%r{^diff --git a/.+ b/(.+)$}).flatten + puts "Files considered (#{files.size}):" + files.each { |f| puts " #{f}" } + puts "ANALYSIS:\n#{chat!(:report).response}" + puts(agent?(:fixer) ? "Fixes applied." : "(Next time, run with `-- fix` to auto-apply suggested edits)") + end end end