jitsusama/convention-recurrence-sensor-guide

Convention Recurrence Sensor

The convention gates exist to stop the same correction being typed twice. This sensor measures whether they work: it counts how often a convention correction recurs in the session logs, by category and by week, so a recurring category that bends down after the gates ship is the evidence the fix landed.

The same query that diagnosed the problem is the sensor that tracks the fix. There is no separate instrumentation to trust.

Running It

node scripts/convention-recurrence.ts [--since YYYY-MM-DD]

Node strips the TypeScript types and runs the file directly; no build step is involved. A MODULE_TYPELESS_PACKAGE_JSON warning on stderr is benign, the output is on stdout. --since limits the scan to logs on or after a date.

The output is a tab-separated table, one row per ISO week, one column per category. Each cell is the number of distinct sessions that quarter a correction in that category that week, so a single ranty session counts once, not ten times. Distinct sessions per week is the right grain for "does this keep coming back".

The Categories

The classifier looks for the strong correction signals, not every phrasing. It favours precision over recall: a trend that bends is the goal, not a precise census.

• emdash: a complaint about emdashes, or the character or its escape appearing in a correction.
• spelling: a Canadian-versus-American or British spelling correction.
• sections: a rebuke about inventing or adding sections to a PR or issue body.
• slack-format: a correction about pipe tables, malformed lists or image embeds in Slack.
• commit: a correction about conventional-commit shape or imperative mood.

The patterns live in scripts/convention-recurrence.ts and are exercised by tests/scripts/convention-recurrence.test.ts. Tune them there if a real correction is being missed; keep precision high so the trend stays meaningful.

Recorded Baseline

Captured 2026-05-31, scanning from 2026-04-01, before the convention gates and the resident block had any effect. Distinct sessions per week:

| Week | emdash | spelling | sections | slack-format | commit | |----------|--------|----------|----------|--------------|--------| | 2026-W14 | 13 | 0 | 0 | 0 | 0 | | 2026-W15 | 5 | 0 | 0 | 0 | 0 | | 2026-W16 | 11 | 1 | 0 | 0 | 0 | | 2026-W17 | 3 | 2 | 1 | 0 | 1 | | 2026-W18 | 5 | 0 | 0 | 1 | 1 | | 2026-W19 | 3 | 1 | 1 | 2 | 1 | | 2026-W20 | 2 | 0 | 6 | 0 | 1 | | 2026-W21 | 7 | 1 | 6 | 1 | 4 | | 2026-W22 | 6 | 0 | 2 | 0 | 3 |

emdash recurs every single week, sections spike in the closing weeks, and spelling, slack-format and commit recur intermittently. These are the curves to watch. Re-run a few weeks after the gates have been active and compare: the convention categories should bend toward zero as the gates catch violations before they reach a correction.

What It Does Not Measure

This counts corrections the user typed, the pain the gates remove. It does not count the gate blocks themselves (those are the gates working, not the user correcting). A separate rise in gate blocks with a fall in user corrections is the healthy signature: the gates are absorbing the corrections the user used to type.