Assess Change Fit Tool
assess-change-fit-toolPre-flight fit check for a change you are about to open as a pull request. Pass the
numstat of your working diff (or, failing that, its additions, deletions, and
changed-file counts) and Coderbuds answers whether the change fits how this team
ships: a verdict with reasons, the team's own merged-PR size norms (median/p75) and
merge time by size category, and the current review-queue pressure. Pass repository and that queue is scoped to it —
human-authored open pull requests on the repo you are working in, not every repo the
team owns, because "review one of these first" is only actionable if you are near
them.
Four verdicts, and only two of them ask anything of you. fits — go. fits_at_edge —
over the standard but inside its tolerance, which is stated for the record and needs
no action, because changes this close to the line merge like changes under it.
caution — meaningfully over; weigh the guidance. split_required — effectively
unreviewable; split it.
Coderbuds applies its own opinionated standard (on by default, teams can opt out): changes well above the standard size get at least a caution regardless of what the team's historical norms would allow — reported as team_norms.target_total_changes.
Also pass review_goals: the distinct outcomes a reviewer must approve in this
change. Describe outcomes, not implementation layers — an API, UI, migration, tests,
and docs that deliver one behavior are one review goal. One goal fits. Two prompt a
caution to confirm they really must ship atomically. Three or more require a split.
This is the scope-coherence standard: a small diff can still be hard to review when
it bundles unrelated decisions. If multiple goals truly cannot ship separately, use
scope_rationale to preserve that context and record the decision after the check.
Best results: pass numstat, the raw output of git diff --numstat <base>.... Coderbuds
then works out the split from the file paths itself — tests, documentation, generated
files (lockfiles, snapshots, minified bundles) and binary assets are identified and
discounted, so the verdict judges the CODE a reviewer actually has to read. 400 lines
of blog post and 400 lines of business logic are not the same review, and without the
paths there is no way to tell them apart.
Failing that, declare the split yourself: test_lines (changed lines living in test
files, e.g. from git diff --shortstat -- tests/) and moved_lines (code relocated
without behavioral change, e.g. an extraction refactor) are subtracted from the
verdict, because a raw count punishes test coverage and double-counts refactors.
Report these honestly; they are recorded with the check and visible to the team.
Do the same for files with test_files and moved_files. A rename sweep, codemod, or
file-move refactor touches a lot of files with almost nothing to read in each, and the
file count is judged separately from the line count — so without these a mechanical
change is called oversized on file count alone. git diff --shortstat -M and
git diff --summary will tell you how many of the changed files were renames.
When the verdict is not "fits", say what you did about it with record-change-fit-decision
— including when you proceed anyway. Overriding is allowed; overriding silently is what
leaves the standard unable to learn it is in the wrong place.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| numstat | No | Strongly recommended: raw `git diff --numstat <base>...` output (tab-separated "added deleted path" rows, `-` for binary). Coderbuds counts the lines and files from it and classifies the paths itself, discounting tests, docs, generated files and binary assets, so the verdict judges the code a reviewer must read. Supersedes test_lines/test_files when given. | |
| additions | No | Lines added in the proposed change (e.g. from `git diff --shortstat`). Required unless numstat is given; worked out from the numstat when omitted. | |
| deletions | No | Lines deleted in the proposed change. Required unless numstat is given; worked out from the numstat when omitted. | |
| repository | No | Optional "owner/name" repository slug the change targets (e.g. patchstack/hub). | |
| test_files | No | Optional: how many of the changed files are test files. Discounted from the file count the same way test_lines is discounted from the line count. | |
| test_lines | No | Optional: changed lines that live in test files (e.g. from `git diff --shortstat -- tests/`). Discounted from the verdict — test coverage is not review burden. Ignored when numstat is given. | |
| moved_files | No | Optional: how many of the changed files were renamed or moved rather than edited (see `git diff --summary`). Discounted from the file count — without this a rename sweep is judged oversized on file count alone. | |
| moved_lines | No | Optional: lines that are relocated code, not new logic (e.g. an extraction refactor). Discounted from the verdict — a raw diff double-counts moves. Estimate honestly; recorded with the check. | |
| review_goals | No | Strongly recommended: the distinct outcomes a reviewer must approve. Describe user or system outcomes, not implementation layers; supporting code, tests, docs, and migrations for one behavior are one goal. One fits, two get a caution, and three or more require a split. | |
| changed_files | No | Number of files changed. Optional but improves the size categorization. | |
| scope_rationale | No | Optional: why multiple review goals must ship atomically. This preserves the reasoning for the team but does not silently waive the scope standard. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| team | Yes | Team name. | |
| reasons | Yes | Why the verdict is what it is, in plain language. | |
| verdict | Yes | The strongest result across active standards: fits | fits_at_edge (over the size standard but inside tolerance — stated, no action expected) | caution | split_required. | |
| check_id | Yes | Id of the recorded check — pass it to record-change-fit-decision to say what you did about this verdict. | |
| guidance | Yes | Concrete next steps when the change does not cleanly fit. | |
| proposed | Yes | The proposed change: additions, deletions, changed_files, total_changes, the discounted surfaces (test_lines, moved_lines, docs_lines, generated_lines, test_files, moved_files, docs_files, generated_files, binary_files), reviewable_changes and reviewable_files (what the verdict judges), size_category (tiny|small|medium|large|oversized, of the reviewable surface). | |
| standards | Yes | Per-standard results. `size` reports its own verdict and threshold; `scope_coherence` reports assessed|not_assessed|disabled, the normalized review goals, rationale, reason, and guidance. | |
| repository | No | Matched team repository slug, or null if none given/matched. | |
| team_norms | Yes | The box: merged PRs analyzed, median/p75 total changes, the Coderbuds standard size ceiling when active (target_total_changes), and average merge-time hours by size category. | |
| review_queue | Yes | Current open PR count, how many are awaiting a reviewer, and how many have waited past the Coderbuds review-turnaround standard. Scoped to the repository when one was given. PRs left unreviewed for over a month are reported separately as `abandoned` and excluded from the awaiting/stale pressure counts — they call for closing, not reviewing. |