Skip to content

Latest commit

 

History

History
27 lines (14 loc) · 4.98 KB

code-quality.md

File metadata and controls

27 lines (14 loc) · 4.98 KB

Code quality

A fleet of agents can make a codebase worse faster than a person can read the diffs. sdlc measures complexity mechanically and acts on the number, so a function that becomes hard to follow is caught at the point it crosses a line, not sometime later when someone happens to open the file.

The same measurement — lines of code, cyclomatic complexity and parameter count per function, computed with a language-agnostic complexity tool so no per-language setup is needed — feeds two different checks. Neither one runs a model until a threshold is actually crossed: the numbers decide whether a review comment or a task gets written at all. The thresholds themselves are a repository setting; see settings.

Two places it acts

In a task's own review. When a task's diff is reviewed, the reviewer measures every function the task touched, at the base and at the head, alongside the usual checks against the task's acceptance criteria. A function that crosses a threshold is a requested change, named concretely enough to act on — extract this branch into its own function, split this one up — and the worker fixes it in the same branch before the task can merge, the same way it would act on any other review comment. A function that got measurably worse but stays under the limits is only a note on the verdict; it doesn't block the merge. A function the task didn't touch is never mentioned, even if it was already over the limit — that's not this task's problem to fix, and blocking an unrelated task on unrelated debt would make small changes carry the cost of a much bigger cleanup.

Across a whole branch. A task-scoped check can only see what one task touched, so it can't catch a function that crossed a threshold before any of this existed, or one that several unrelated tasks each nudged a little further over. Branch analysis looks at everything and runs on a cadence you choose rather than a diff you're already reviewing, which is why it's a separate mechanism instead of a bigger version of the task review.

Branch analysis does nothing when the branch's current head has already been analysed, and does nothing else when an epic is already open for analysing that branch: the open epic is a lock, so a second sweep can't file overlapping work while the first round's fixes are still in flight. Once an analysis is due and the branch does have functions over a threshold, it creates an epic named after the branch and the commit, with the crossing functions recorded on it, and one task under that epic whose job is to turn those functions into refactor work.

The analyst

That task is owned by a dedicated role — an agent that reads the flagged functions and their callers, decides what each one actually needs (extract, split, dedupe, or nothing if it merely reads awkwardly but does one clear thing), and groups the ones worth changing by the files they touch. Two findings in the same file, or in files that import each other, become one task; only groups that don't overlap become separate tasks that can run in parallel. This role never edits code and never commits — it only turns numbers into scoped work, or, for a finding it decides isn't worth a change, a comment explaining why.

Keeping that judgment in its own role rather than folding it into the branch's next task, or leaving it to whoever notices, matters for the same reason task review and branch analysis are separate: deciding how to group and scope a refactor is a different job from doing the refactor, and mixing the two would mean the person fixing the code is also the one deciding how much fixing is warranted.

The refactor tasks it files are ordinary tasks from that point on: they go through the same dispatch, the same review, the same merge queue as anything else, scoped to the paths they touch and with the same complexity check as their pass condition. Nothing about them being refactor work gives them a different path. The epic they belong to closes once they're all done, which releases the lock and lets the next commit on that branch be analysed.

When it runs

Branch analysis can be triggered by hand for a chosen branch, and reports back with what it did: nothing to do, already busy with an open epic, no functions over the limit, or what it filed. It can also run automatically, on every sweep the supervisor makes, for the branch dispatch currently targets and for the branch of every epic in progress — off by default, so nothing files work on its own until that's turned on. Because the lock and the already-analysed check make a repeat call free, it's also safe to call from a cron job or a CI step on the same schedule as anything else.

Refactor epics and tasks show up like any other work once filed, and their cost shows up alongside every other task's. Reviewing them by hand before they merge, or turning branch analysis off again, both work the same way they would for any other task or epic. See keep code under the limits for turning this on and tuning it.