Skip to content

Review pull requests with a model, and say why a feature belongs - #120

Merged
cedvdb merged 1 commit into
mainfrom
feat/ai-reviewer
Nov 10, 2026
Merged

cedvdb merged 1 commit into
mainfrom
feat/ai-reviewer

Conversation

@cedvdb

@cedvdb cedvdb commented Nov 10, 2026

Copy link
Copy Markdown
Owner

What this adds

A reviewer for every pull request, the same machine as phone_form_field runs: read against
.github/agent/review-prompt.md, answered in one comment with one ai: label, edited in place
when the branch moves.

file what it is
.github/agent/review-prompt.md the judgement: eight checks, and the JSON the answer comes back in
.github/agent/triage.py the rules: verdict → label, the merge guard, the comment. --self-test runs offline
.github/agent/collect.py the input: the PR, its file list, its diff ordered and capped, and this package's own scope
.github/workflows/review.yml the run: one HTTPS call, one comment, one label
.github/agent/README.md the labels, the switches, and what it never does

It is this repository's rules, not a copy

The widget library asks contributors to bump pubspec.yaml and add a CHANGELOG.md heading. This
repository does not: 9.0.28 is a single release commit, and the monthly metadata workflow bumps its
own version. So asking a contributor for a version bump here would be noise, and the mechanical checks
are different:

phone_form_field here
version + changelog on a PR required not expected — flagged only if a diff moves it alone
generated code lib/src/localization/generated/** needs the .arb lib/src/metadata/generated/** needs resources/
dependencies Flutter is normal Flutter is blocking — this is pure Dart

Those two are enforced in triage.py, not asked for in the prompt, so no reading of a diff can
disagree: a hand-edited generated map, or a pubspec.yaml that gains Flutter, comes out as
ai:changes-requested whatever the model answered.

A feature has to earn its place

A fix is judged on whether it is correct. A feature is judged on whether it should exist: whose
problem it solves, whether anyone asked for it, and whether its cost is proportionate. When it accepts
one, the reviewer must write the argument, and the comment carries it as Why it belongs here. An
acceptance with no argument is not an acceptance — triage.py turns it into ai:needs-review,
because that part is a person's to decide.

To judge "this already exists" as a fact rather than a guess, collect.py puts the README's feature
list and the exported surface in front of the model, read from the base branch.

Turning it on

One secret is the whole feature; without it the job runs, logs a notice and does nothing.

gh secret set GEMINI_API_KEY --repo cedvdb/phone_numbers_parser

Merging stays off (AUTO_MERGE unset) — the bot labels and comments only. .github/agent/README.md
documents the switches and why it refuses to arm a merge on a branch with no required checks.

Checks

  • triage.py --self-test — 52 cases, offline
  • the workflow parses, all twelve run: blocks pass bash -n
  • collect.py on this checkout finds the Features list and the seven export lines
  • three end-to-end renders: a hand-edited generated map and a Flutter dependency are both
    overruled to changes-requested naming the rule, and a parser fix with its test is accepted

No dependency changes, no version bump, and nothing in lib/ is touched — this pull request adds a
reviewer and nothing else.

Every pull request is read against .github/agent/review-prompt.md and answered in one comment with
one ai: label: accepted, changes-requested, out-of-scope or needs-review. The comment is edited in
place when the branch moves, so a pull request carries one review rather than one per push.

The judgement is this repository's, not a copy of the widget library's. Three differences matter:

- versions and changelogs are cut at release here (9.0.28 is the shape of one, and the monthly
  metadata workflow bumps its own), so the reviewer does not ask a contributor for either — it
  flags a diff that moves the version on its own, because publishing is a human's decision;
- lib/src/metadata/generated/** is produced by resources/generate_files.dart, so editing it without
  touching resources/ is blocking, mechanically, whatever the model answers;
- this package is pure Dart on purpose, so a pubspec.yaml that gains a Flutter dependency is
  blocking for the same reason: the widget library depends on this one, not the other way round.

A feature has to argue for itself: the answer carries a case naming the problem it solves, the method
it does not duplicate or the issue it answers, and triage.py will not let an acceptance stand without
one. The reviewer is given the README's feature list and the exported surface to judge that against,
because a diff can show what a change adds and never what was already there.

Merging is off until AUTO_MERGE says otherwise, and refuses to arm on a branch with no required
checks: an automerger that merges before CI is worse than none.
@cedvdb
cedvdb merged commit d004366 into main Nov 10, 2026
1 check passed
cedvdb added a commit that referenced this pull request Nov 10, 2026
Create Tag from pubspec.yaml failed on the push that merged #120:

  ❌ Tag v9.0.29 already exists on remote. Failing workflow.

That is not a change going wrong. v9.0.29 was tagged when #119 merged, #120 changed nothing that
ships, and the workflow treats "already released" as an error. So every merge that does not bump the
version leaves a red run on main, and a red X that fires on ordinary merges stops being read.

An already-tagged version is now a notice and a skip. The changelog guard is unchanged and still
runs, but only when there is a tag to create, so a version bump without a `## x.y.z` heading still
fails — which is the check this workflow exists for.
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