Readability.ColemanLiau's message says 'below 19' but its condition fires at 9

[theredspoon]

What's wrong

testdata/styles/Readability/ColemanLiau.yml's message and its actual firing condition don't agree:

message: "Try to keep the Coleman–Liau Index grade (%s) below 19."
condition: "> 9"

The rule reports once the computed grade passes 9, but tells the user to keep it below 19.

The message is very likely the bug, not the condition

Every other formula in this same style has its message threshold exactly match its condition:

Formula	Message says	Condition
FleschKincaid	below 8	> 8
FleschReadingEase	above 70	< 70
GunningFog	below 10	> 10
SMOG	below 10	> 10
LIX	below 35	> 35
AutomatedReadability	below 8	> 8
ColemanLiau	below 19	> 9

ColemanLiau is the only one where they diverge. Coleman-Liau's grade output is on the same US-grade-level scale as FleschKincaid's and AutomatedReadability's, both of which use 8 as their threshold, so 9 fits the pattern the rest of the style already follows. It also matches published guidance directly: general-audience writing is commonly recommended to target a Coleman-Liau grade around 8-10, with several sources specifically citing "8 or less" for public-facing content (readable.com, readabilityformulas.com). A threshold of 19 sits past graduate/academic-level prose on this same scale and would rarely fire on real writing.

Traced the file's actual history via the GitHub API, since local shallow clones don't have it. It's been touched exactly twice since it was created: a140d309 ("feat: add Readability style", 2021-11-14), which added it fresh with these exact values, and a pure rename in 2022 with no content change. The founding commit also corrected FleschReadingEase's threshold from 50 to 70 in the same diff, confirming a deliberate tuning pass rather than a rushed first draft. That makes a simple transposed digit (9 becoming 19) in the message string a more likely explanation than a leftover placeholder value, sitting unnoticed for about four years since nothing exercises the message text in a way that would surface the mismatch.

Proposed fix

Correct the message to match the condition:

message: "Try to keep the Coleman–Liau Index grade (%s) below 9."

Not the other way around: 9 is consistent with the rest of the style's thresholds, so it's the condition that's very likely correct.

Found while researching a check[...] rollup formula for #1163, not otherwise related.

[jdkato]

This is an internal test fixture, not a user-facing style. The published Readability package is here, and it has said below 9 since March 2022.

Please understand that Vale is maintained by one person, and that I actually need to review and try to understand all code submitted.

You've opened seven pull requests and three issues in three days. I know it's very easy to contribute with AI, but a multi-paragraph issue and PR about an internal typo — with no mention of the public repo — takes far longer to evaluate than it took to produce. The history section here traces the file through this repo and concludes it sat unnoticed for four years; a look at the package that actually ships it would have shown it fixed in 2022, and this would never have been written.

I'm not saying the intentions are bad, but this style of contribution puts a lot of cognitive load on the maintainer. My suggestion is to slow down a little: identify problems that are actually impacting you, open an issue, allow time for discussion, and then move to a PR. That pace gives everyone a realistic chance to understand the code and agree on ideas.

---

In the meantime, I'll work on CONTRIBUTING.md to better explain my position.

[theredspoon]

Hi @jdkato, human here.

First and foremost, I apologize for wasting your time and attention with this specific PR #1172 and its corresponding issue #1171.

Second, thanks for giving your attention to any of the work that I did. My intentions are to make it as easy as possible for you to do your review work on your own time.

I think there are a few issues with your suggestion I want to call out:

1. Slowing down and pacing contributions out assumes my attention and motivation are elastic. They're not, any more than your cognitive load is something you can expand on demand.

I see a project I want to improve. I do something about it. I have very little visibility into who’s on the other end of a repo or when they’ll next look at it. I want to ship my contribution at a high bar, on my time, and move on. That's how I've always understood open source contribution to work.

I'm not asking you to review on any timeline, and I'd ask the same in return. I'll keep contributing the way that fits my attention, you take whatever time this needs.

2. I don't know your availability so I don’t presume you are open or accessible for discussion on a timeline that works for the both of us.

Before your comment, I'd already checked:

• how long PRs from outside contributors typically take here: recent merges run a median of about five days, most within a week, a few sitting much longer.
• how active you are based on your commit activity in the repo’s insights: it spiked the week of July 26 and tapered off in the last few weeks.

After your comment, I also checked your comment history: you respond roughly every few days, though that's not something the GitHub UI surfaces on its own.

None of this tells me what will happen with my work effort, or when you'll have room for it.

To work around that unknown and reduce your cognitive load as much as possible, I put real effort into making sure my work held up, including carefully following your existing instructions.

3. Your request to slow down and your CONTRIBUTING.md are at odds.

I initially raised two issues (#1161 and #1163) that mattered to me and submitted one PR each. Then, I encountered a number of bugs along the way, splitting them out into single-concern PRs very closely following CONTRIBUTING.md and what I read as the intention behind your comment in #938 (comment).

I can appreciate that may feel like high cognitive load. It seems like that is a consequence of following your instructions.

I suggest that instead of asking contributors to pace their efforts differently, you instead make it clear that your review happens at your pace.

I assumed that was true because you say you’re the sole developer directly on the repo’s landing page. But perhaps you may feel you need to make that through line explicit.

Additionally, you can introduce one or more “bowl of blue M&Ms” tells to determine in advance whether someone has followed your guidelines in CONTRIBUTING.md so you have an additional signal for what level of cognitive load you might expect.

Look, I understand that AI is putting novel demands on our cognitive load. There's a lot of surface area to cover when contributing, and I try to cover it rigorously, but I still get things wrong sometimes. In fact, I am hoping to use vale in my projects and my org to meaningfully lower that load.

I wish you and your project great success and I hope my contributions will be worthwhile.

I am open to discussion. If you have any feedback on content, or want more context on how I approached the problem, I'm happy to share and will aim to turn it around quickly.

[jdkato]

My intent wasn't to make assumptions about your attention or motivation. But you've asked me to review over 6,000 lines of code, submitted over 3 days, and this is the first discussion we've had. I don't think it's unreasonable to suggest that discussing ideas before writing the code is a good idea and would save us both time.

[jdkato]

For full transparency, I've enabled GitHub's fairly new pull request limits setting, which caps how many PRs a contributor can have open here at once.

[theredspoon]

Ok, understood. Please consider also adding a Discord CTA to the repo landing page and CONTRIBUTING.md with some context for its use.