Personally I found it quicker to write comments by hand, than to try and
force the LLM to produce a sensible Note.
The next best thing in my experience is to write a rough draft and let a LLM
fill in the details. This way your input on what to emphasise, and what
can be
ignored will transfer over to the final text for the most part.
Skills or instructions like "be concise" reduce the wordiness/rambliness
but don't
do much to guide the focus of the text. So they are an improvement. But
they often
also result in useful context being removed.
----------------------------------------------------------------------
About
https://gitlab.haskell.org/ghc/ghc/-/merge_requests/16543#note_700940
it's not *confusing*. It's just exhausting to read. There is terrible
signal:noise ratio and a complete lack of focus.
Since you asked, when looking at the commit message from
a0539f8ed059a72186dc6fdeb5649ade4eb4ddbe and starting with the title:
Cmm: delete losing blocks in common block elimination
What does this tell me. Cmm is fine. common block elimination is fine.
But half of this sentence reads as noise. Deleting blocks is the point
of CBE. so yes I would expect it to do that.
Something better would be something like Cmm: Drop duplicate blocks
during common block instead of just rewriting labels.
Likes yes it's not *terrible*. But it's not great. And what makes it
terrible is that all of it is not great. Because if we move on:
Delete each merge's losing block in the pass itself, instead of
leaving it in the graph, unreachable, until stack layout drops it.
Just like any great novel it starts by repeating the title. I'm joking
of course. Sometimes that can be fine but no one will read the body
without the title. So again not *terrible* but lowkey bad. Then it
rambles on: "Leaving them in the graph", where else would we leave them,
if the graph is the only output. "unreachable", well yes or we couldn't
drop them. "stack layout", I would have just said a later pass, because
it doesn't matter much which one. But maybe I'm being nitpicky on that
last one.
This is safe:
This is low key pointless again. If it were not safe why would we merge
it. We are deleting duplicate blocks that are *already* dropped by
another pass before this commit. Why would it not be safe? It does not say.
replaceLabels rewrites every in-graph reference to a loser
to the end of its substitution chain, and chain ends never lie in the
substitution's domain.
This is meaningless to anyone who hasn't already read the code. If they
have read the code it's meaningless too. Because you already know this
information.
Which just makes this paragraph meaningless.
The one reference replaceLabels does not rewrite,
info_tbls, holds only the entry block's info table at this stage, and the
entry block never loses a merge -- see
Note [Retain entry block during common block elimination.]
What is info_tbls? What is replaceLabels? Again if I know the code
enough to remember this then this is of zero value. If one doesn't know
the code then it's a soup of references to things in the code we haven't
seen before. It doesn't help anyone understand what the MR does without
reading the code. But even if you read the code this is not really
helpful to understand it.
At best this tells an LLM some keywords to grep for. But it will just
look at the diff anyway. The information anyone will gain by looking at
this will be near zero. Maybe the Note reference is relevant. Maybe ...
Also rewrite Note [unreachable blocks] in GHC.Cmm.Pipeline to state
who actually removes unreachable blocks and when, and point at it from
GHC.Cmm.ContFlowOpt.
Who is this for? Who would read this and say "I'm glad I could glance
from the git log that this Note was rewritten here". The note is related
to the change so it was touched up. That should happen. But who wants to
read about this in the commit message. I wouldn't. A LLM wouldn't. A
maintainer cherry picking the commit wouldn't. Someone bisecting a bug
wouldn't. A reviewer wouldn't. I think it's noise. Word shaped noise.
Filling the commit message up to the length the LLM thinks it should
have and nothing more. -------------------------- I have forgotten what
this MR was about since I left the comment.
All that re-reading of the commit message told me was we drop some dead
code in another place now. For unknown reasons. And unknown benefits. In
ways I can't really gleam from the commit message either.
It tells me almost none of the things I care about in a commit message,
and a lot of things I don't care about.
It's just bad. Bad in a myriad of tiny ways that I can point at exactly.
And for any one of them one could say maybe it's not that bad. But once
you throw enough pixels at a screen you get a picture. And clearly this
picture is just bad.
So I hope we can do better. One way or another. On 14/10/2026 15:00,
Simon Jakobi wrote:
Thanks for your message and your review efforts, Andreas!
This is an issue I've been struggling with, primarily in my own
patches. Recently I've often spent more time and effort trying to get
the prose into an acceptable shape than on any other aspect of a
patch. While I believe that this has been fairly effective at removing
unnecessary context, the readibility of the result is often still not
great, so I'd be very interested to learn how other contributors
manage to achieve good quality comments with their LLM-assisted
workflows.
Regarding your MR feedback: Do you think you could point out
relatively precisely _what_ you regard as a problem, e.g. bad wording,
unnecessary factoids, etc?
For example, in
https://gitlab.haskell.org/ghc/ghc/-/merge_requests/16543#note_700940
you complained about the "LLM Rambling", but I couldn't tell which
comments or commit messages you actually found confusing, and why. (I
had actually invested several hours into them.)
I understand that my request takes even more effort from you – I will
try to make it pay off.
Thanks!
Simon
Am Mi., 14. Okt. 2026 um 13:08 Uhr schrieb Andreas Klebinger via
ghc-devs<[email protected]>:
Hello Devs,
Given the use of AI has increased recently I think this deserves discussion.
There are certain texts that are, ultimately, transient, or read less
frequently as time moves on.
This broadly includes tickets, which generally become mostly irrelevant once
resolved.
While reading AI tickets can be exhausting, I'm willing, within reason, to
accept them as a fact of live.
But there are parts of the code base in which we have prose that is written
once and read
often. I'm primarily concerned with Notes, Commit messages, and to a lesser
degree code comments.
I've noticed more people have been posting LLM generated bug fixes (fine, it's
policy) where
seemingly little work went into polishing texts other devs will read many
times. I consider this a problem.
I think it's important for certain parts of the code base to be written
concisely. Something LLMs
are terrible at today, and even skills make it marginally better. This is just
a fact.
I think especially with the release of Opus 5.5 this has become *more* of an
issue as the prose is
now only bad in a myriad ways that are not immediately obvious rather than
being obviously atrocious at a glance.
Which leads people to take it as-is without putting effort into writing it by
hand, or at least trimming it down after the fact.
This is obviously bad for human consumers of these texts. But even if you are "all
in" on AI these texts
are also objectively garbage for future AI use as they are bloated with
irrelevant facts, meaningless past
history, repeating things obvious from context and generally wordy for no
benefit.
They are simply bad.
Is it fair to expect people to put in more effort into these? I think yes.
Notes are *the* way to understand the code base. And making them worse
permanently
degrades the ability of newcomers to understand the codebase. Similarly commit
messages
are hugely important to be able to determine when changes where introduced,
quickly find
ranges of commits to bisect for new bugs and many more regular maintenance
tasks.
My plan is to aggressively request improvement of prose during MR review going
forward.
Accepting bad prose is worse for maintainers because they have to read texts
three times to understand what is going on.
It's worse for agents because it fills context windows with irrelevant facts
and pointless trivia that poison their
reasoning ability.
It's just worse, and it takes little effort to fix.
But maybe I'm alone in feeling this way. If everyone else is happy to read Opus
text output all, or at least to have opus read opus
output all day long. Then I will surrender this fight and move to another hill
to die on.
But if people are feeling similarly then please let me know and do likewise.
I don't think it's a big ask either. If you are prompting already just type a
draft in your commit message/note and let claude do
formatting/typo/alignment fixes. A sloppy text pushed through claude will in
most cases beat what any model today
will generate on it's own. Maybe this changes in 2 years. But it's not changing
today.
It's not just a question of length. You can make a LLM generate shorter texts
with a skill file or otherwise.
But they are terrible at understanding what the tricky parts are, what is worth
highlighting, what can
be dropped because it is obvious from wider context.
I think it's *easy* for every contributor who knows what is happening in their
patch to reach a reasonable standard.
But we have to ask them to do it and to set the expectation. And I hope we can
do so.
Andreas,
freshly back from reading some claude output.
_______________________________________________
ghc-devs mailing list [email protected]
To unsubscribe send an email [email protected]
_______________________________________________
ghc-devs mailing list -- [email protected]
To unsubscribe send an email to [email protected]
