Skip to content

[SCR-216] Accept the heading names repos use - #220

Merged
itsryanarmani merged 2 commits into
mainfrom
scr-216-accept-existing-heading-names
Sep 2, 2026
Merged

itsryanarmani merged 2 commits into
mainfrom
scr-216-accept-existing-heading-names

Conversation

@itsryanarmani

Copy link
Copy Markdown
Owner

Closes #216

What

Each required heading gains a set of accepted names. A section matches under any of them, and failure messages still name the canonical heading so new issues converge on one vocabulary.

Why

The standard invented a vocabulary and the fleet already had one. Counted across the open issues in content-rabbit:

23  What          the form asked for "Today / Wanted"
17  Scope         the form asked for "Out of scope"
12  Why           the form asked for "Job to be done"
11  Done          the form asked for "Acceptance criteria"
 7  Verification  the form asked for "How to verify"
 6  Problem       the form asked for "Job to be done"
 4  Deliverables  the form asked for "Slices"

Same concepts, shorter names, in use before the standard existed. AGENTS.md says to read a repo and reuse its domain terms; the standard did not, and took its names from the spec-issue skill and another team's conventions instead.

Correcting the claim that motivated this

The issue said most of the 133 failures came from this naming mismatch. That was wrong, and the measurement says so:

failures across all 133 open issues   before 547   after 543   removed 4
issues that improved                  4

Broken down by type after the change:

82  state label       306 label failures
82  route label
72  kind label
70  size label

10  ## Out of scope    26 heading failures
10  ## Job to be done
 6  ## Slices

92% of failures are missing labels, not heading names. That is expected rather than alarming: the label vocabulary existed in one repo out of five until #215 rolled it to the rest, so the issues had nothing to carry. Applying labels to existing issues is triage work, not a tooling change.

This change is still worth making. It stops the checker failing an issue for spelling, and it stops it failing every future issue written in the fleet's own vocabulary. It is a smaller win than the issue claimed, and the numbers above are the honest size of it.

The bug this found

Exit gate was in the first draft as an alias of Acceptance criteria. Running it against real issues showed why that is wrong: an epic is forbidden from carrying acceptance criteria, ten phase epics legitimately carry an Exit gate, and the alias made all of them fail a rule they do not break.

A gate is a condition for leaving a phase. Acceptance criteria are the testable statements of one issue. They are not the same thing and are no longer treated as one name.

That was found by running the change against live issues, not by reading it.

How I verified

node issue-standards.test.mjs      -> tests 40, pass 40, fail 0   (29 before, 11 added)
./issue-standards --selfcheck      -> exit 0

The four cases that matter, checked directly rather than trusted:

epic carrying "Done"        -> refused        (alias of a forbidden heading)
epic carrying "Exit gate"   -> accepted       (not a forbidden heading)
feature in fleet vocabulary -> accepted       (Why / What / Done / Verification)
bug with "Impact"           -> accepted       (Impact stays canonical for a bug)

Aliases go through the same label equality that lint already used, so a heading named in a form's description still does not count as an offered field. That hardening arrived from review on #192 and is deliberately not weakened here.

How it was built

Delegated to grok-4.6-xhigh through the devin CLI. The alias map, namesFor(), the findSection change and the offers() helper that keeps lint strict are its work, and it correctly extended the forbidden-heading check to aliases, which was the part most likely to be missed.

Review found one design error, the Exit gate alias, and it was mine: it was in the brief I gave. Three earlier attempts produced nothing because of permission flags I chose wrongly, not because of the model.

Assisted-by: claude-personal-1:claude-opus-5

The standard invented a vocabulary and the fleet already had one. Every
open issue in content-rabbit failed the checker, and most of that was
the form disagreeing with an established convention rather than issues
being thin.

Counted across the open issues: What 23, Scope 17, Why 12, Done 11,
Verification 7, Problem 6, Deliverables 4. Those are the same concepts
under shorter names that were in use before the standard existed.
AGENTS.md says to read a repo and reuse its domain terms, and the
standard did not.

Give each required heading a set of accepted names. Failures still name
the canonical heading, so new issues converge on one vocabulary while
old ones stop failing for spelling.

Exit gate is deliberately not an alias of Acceptance criteria. A gate is
a condition for leaving a phase; criteria are the testable statements of
one issue. An epic is forbidden from carrying criteria, so treating the
two as one name made every phase epic fail a rule it does not break.
That was found by running the change against real issues rather than by
reading it.

Aliases go through the same label equality that lint already used, so a
heading named in a description still does not count as a field.
@coderabbitai

coderabbitai Bot commented Sep 2, 2026 •

Copy link
Copy Markdown

Warning

Review limit reached

Next included review available in 25 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available. Your 108 included PR review attempts over the past 7 days set your current allowance at 1 review per hour.

Your organization has reached its usage spending cap. Adjust your spending cap in the billing tab.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Team

Run ID: ad1022d6-136c-430f-9b21-185e85ba2360

📥 Commits

Reviewing files that changed from the base of the PR and between 0351fb7 and decb75e.

📒 Files selected for processing (2)
  • issue-standards.mjs
  • issue-standards.test.mjs

Comment @coderabbitai help to get the list of available commands.

… canonical one

findSection took the first section whose normalised heading matched any
alias, so a stray "## Why" ahead of a filled-in "## Job to be done" made
validateBody report the required heading as empty. It now prefers whichever
match has real content. Also adds lintTemplates coverage for a required
heading offered only through an alias label, and for a forbidden heading
offered the same way.

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed head: decb75e291aedc3e96c9ed2aa7bbba015a10b5f0

Council findings verified against the code; one confirmed, two discarded. No fixes pushed this cycle — the one confirmed issue is proof text that only the author can correct, and the discarded items are described below.

Confirmed (Major) — ## How I verified is stale

The PR body reports node issue-standards.test.mjs -> tests 40, pass 40, fail 0 (29 before, 11 added). That count matches the state right after the first commit (75ac43b), which does add exactly 11 tests to reach 40. But the second commit (decb75e, the current head) adds 3 more tests (lint accepts a required heading offered only through an alias label, lint rejects a forbidden heading offered only through an alias label, and the stray-alias-collision test) — the file now has 43 test( calls and this diff adds 14, not 11. The verification block was never rerun after the fix commit that changed findSection's collision behavior, so the reported numbers describe a version of the diff that no longer exists. Please rerun node issue-standards.test.mjs on the current head and update the reported counts — I won't fabricate that evidence myself.

Discarded

  • Scope: "alias labels weaken the canonical-only template requirement" (issue-standards.mjs:451-457). Checked: this is intentional and correct, not a regression. A form whose label is an accepted alias (e.g. Why) produces issues whose body heading is that same alias, and validateBody already accepts that alias. Rejecting it at the template-lint stage while accepting it at the body-validation stage would just be a second, contradictory rule. The author added a passing test for exactly this case (lint accepts a required heading offered only through an alias label, line 470), so this is deliberate, not drift.
  • Scope: aliases without measured fleet evidence (Repro, Regression, Last working, Metric, Success metrics). The PR's own census only covers 7 of the ~15 accepted alias names. That's a fair observation about the strength of the justification, but it names no failure — accepting an extra name an issue happens not to use is inert. Not blocking; noted below as a documentation point instead.

Minor (not blocking)

  • issue-standards.md is described in its own first line as "the standard" and still lists only the canonical headings (## Job to be done, ## Today / Wanted, etc.) with no mention that aliases are now accepted. Anyone reading the doc as the source of truth won't know Why/Impact/Scope/Done/... pass too. Worth a short note near "The spine" section, at the author's discretion — not pushed since it's a judgment call whether documenting the aliases undercuts the stated convergence goal.
  • The aliases without measured evidence noted above: consider trimming to the measured set or adding a one-line justification for the rest. Not a functional issue.

PR-standard lens

Branch, title, body sections, single Closes #216, Assisted-by: trailer, and the 500-line/40-file caps (206 counted lines, 2 files) all check out.

🧑‍⚖️ Council
Model Lens Result
GPT-5.6 (Codex) correctness no findings
Gemini 3 Pro performance timed out
Kimi K3 security no findings
Grok 4.5 maintainability timed out
GPT-5.6 (scope) scope 1 confirmed (proof staleness), 2 rejected

Comment thread issue-standards.test.mjs
assert.equal(validateBody(body, 'feature').failures.length, 0);
});

test('lint accepts a required heading offered only through an alias label', () => {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This test (and the two after it) were added in decb75e, after the "## How I verified" block in the PR body was written. That block still reports 40 total / 11 added, but the file now has 43 test( calls and this diff adds 14. Please rerun node issue-standards.test.mjs on this head and update the reported counts.

@itsryanarmani
itsryanarmani merged commit b3f887c into main Sep 2, 2026
4 checks passed
@itsryanarmani
itsryanarmani deleted the scr-216-accept-existing-heading-names branch September 2, 2026 18:06
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.

Accept the heading names repos already use

1 participant