---
title: "Why 889 of 927 JIRA Comments Never Needed a Human Reader"
canonical: https://dxdev.com/blog/writing-standard-enforcement-scale/
datePublished: 2026-09-12
---
The hooks went in clean. The 927 tickets didn't.

We had just finished the engineering: a writing standard for JIRA comments, plus pre-commit hooks that enforce it going forward. No more comments that narrate the diff instead of explaining why the code does something surprising. No more three-paragraph essays where a fact and a warning would do. The hook checks new commits against the standard before they land. That part took an evening.

Then the standard ran against what already existed, and it came back for all 927 open tickets. Every one of them predated the hook by definition, so every one of them violated it. Years of ticket-comment style drift, live at once.

## Why a hook can't retrofit anything

A pre-commit hook only sees the commit in front of it. It has no opinion about history, and it shouldn't, because rewriting JIRA comment history isn't a git operation. Comments live in JIRA's own store, tied to ticket state, workflow transitions, sometimes customer-visible fields. There's no `git rebase` for that. The fix had to be a sweep: pull every open ticket's comment body, run it through the same judgment the hook applies to new commits, and rewrite in place through the JIRA API.

Our first move was to point the same checker script at all 927 and let it run. That was the wrong turn, and it cost about twenty minutes of watching a batch job silently do the wrong thing. The hook's checker was written to flag violations and reject a commit. It was never written to fix one, because in the hook's world the human fixes it and resubmits. Pointed at a backlog of 927 tickets with no human in the loop per ticket, it flagged all 927 and sat there. Nothing shortened. Nothing shipped. We had built a smoke detector and were trying to use it as a fire extinguisher.

## The two-pass judge setup

What worked was two passes. First, an agent reads each ticket's comment thread and proposes a shortened version. It applies the same standard the hook checks for, but it is allowed to rewrite as well as flag. Second, a separate judge agent diffs the original against the proposed rewrite and looks for exactly one failure mode: a dropped fact. It doesn't ask whether the rewrite is shorter or whether it reads better. It asks whether the rewrite lost a decision, a gotcha, a number, an ID, or a non-obvious reason that a future reader would need.

The second pass earned its place because the first pass does drop facts. Two logged runs against the same diff kept the same brief: flag instances where genuine implementation details, gotchas, specific numbers or IDs, or important context got dropped in favor of brevity. One flagged run caught a rewrite that had dropped the `decision='multiteam'` condition under which a check gets skipped. A modifier six months from now would need that, and the shortened text wouldn't have given it to them. Another run caught a dropped detail about which asset references flip at release time. Both facts stay invisible until the person debugging at 2 a.m. needs one and it isn't there.

Anything the judge flagged went back for a second rewrite attempt or got left alone rather than force-shortened. Anything it passed got applied.

## The count that mattered

927 is the total. The number that tells you more is 38: comments long enough, or judged risky enough, that they got routed to a human review queue instead of auto-applied. The other 889 went through the two-pass sweep and landed without a person reading them first.

That ratio is the output of the exercise. A standard enforced only at the point of creation leaves a debt pile the size of your entire open backlog, and the size of that pile is exactly the fraction of your history that predates the rule. The hook stops the bleeding. It does nothing about the wound already there.