Skip to content

feat: add a reusable reviewer package workflow - #395

Closed
johsoe wants to merge 6 commits into
mainfrom
feat/reviewer-package
Closed

johsoe wants to merge 6 commits into
mainfrom
feat/reviewer-package

Conversation

@johsoe

@johsoe johsoe commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

Risk: low. It's a new opt-in reusable workflow, so no existing caller changes. Revert to undo.

Intent

Reviewers open a PR with only the diff to go on. This adds reviewer-package.yml, a reusable workflow that posts one comment with the context the diff lacks. Re-runs edit that same comment, found by its <!-- reviewer-package --> marker.

  • Done when a PR in a calling repo gets a comment with:
    • Related pull requests: PRs anywhere in the org with the same Jira key (from the title or branch name), plus every PR the description links to.
    • Earlier PRs on these files: the top 3 by how many changed files they share, folded by default.
    • Overview (optional, kept terse): a sentence or two on where the change sits, a Mermaid diagram (at most 10 nodes) grouped by app, service and repository (this PR's parts bold, related PRs' parts dashed), and up to 3 files to start with.
    • Cross-repo changes (in the overview): for each related PR, Claude gets its description, files and diff. It says how that PR connects (which side calls which), which must merge or deploy first, and compares both sides of every shared contract: paths, fields, types, nullability and enums. It quotes any mismatch, or says where a diff was missing or cut off.
  • Done when a missing key, a failed or refused Claude call, or a diff too large for gh still posts the comment, just without the overview.
  • Done when a public calling repo never shows PRs from private repos, and nothing in the comment can ping anyone.

Not in scope

  • Before/after screenshots from PR preview deploys. That's phase 2, only for repos with previews.
  • Refreshing the comment on every push. It runs once per PR and on demand. Every-push runs would cost an AI call each time.
  • Feeding the package into the AI code reviewer.

Verified

  • actionlint passes with .github/actionlint.yaml.
  • I ran the collect and comment-building steps locally against several internal PRs (one with a Jira key, one linking PRs in two other repositories, one with 71 files), printing the comment without posting it.
    • GitHub search splits a Jira key into words, so the first version returned unrelated PRs. Hits must now contain the whole key.
    • Linked cross-repo PRs are listed, and their details are fetched with other repositories first. Diffs over 30,000 characters are marked as cut off. A PR that can't be read is warned about and stays in the related list.
  • Private-repo filter: with the calling repo treated as public, private-repo hits are dropped. With it private, they are kept.
  • Sanitizer: Markdown images and <img>/<a> tags are stripped, and every @ before a name gets a zero-width space.
  • I rendered a hand-written sample overview with GitHub's Markdown API plus mermaid 11, to check the grouped diagram and the section layout.
  • Two CI-workflow review rounds. All findings are addressed: token scope, comment race, untrusted model output, the /package match, a mention bypass, silent related-diff failures, and doc drift.

Gaps

  • No live Claude call yet. The first one will be the first caller PR once it leaves draft. The sample overview was written by hand to the same prompt, so the real output's quality, especially the contract comparison, is unproven.
  • Contract checks only see 30,000 characters per related diff. Contracts deeper in a big PR are reported as not visible, not checked.
  • Not run on an ARC runner yet. pr-digest.yml already uses gh and jq on arc-arm64-1cpu-2gb-nodocker.
  • Earlier-PR lookup depends on squash-merge subjects ending in (#123).
  • Links in the model's reply are kept; only images and HTML are stripped.
  • Cost estimate (about $0.10–0.40 per run on Opus 5.5, depending on related PRs) comes from token counts, not a measured run.

Context

  • The first caller is pinned to this branch's latest commit SHA until this merges.
  • Docs: new "Reviewer Package" section in docs/workflow-guide.md, README entry, CLAUDE.md change log.

Pre-merge checklist

  • Reviewed the code — read the actual diff, not just this description, and it matches the stated intent
  • Gaps accepted — read Gaps and happy to merge with those open
  • Tests — the changed behaviour is exercised, and no test or CI gate was weakened to go green
  • Release risk — failure modes, edge cases and load considered
  • Scoping & data access — auth/operator scoping correct; no endpoint left unprotected
  • Deploy & rollout — migrations, env/helm and feature flags safe and correctly ordered

@johsoe

johsoe commented Oct 27, 2026

Copy link
Copy Markdown
Contributor Author

Closing: this moves to a private repository.

@johsoe johsoe closed this Oct 27, 2026
@johsoe
johsoe deleted the feat/reviewer-package branch October 27, 2026 15:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant