You've seen test-rot, specification rot, and documentation rot; we now introduce; prompt rot!
Cluttering the repo with out-dated, very wordy and quickly aging prompts will just confuse any agent tasked with looking at the repo in the future. Keeping context windows down is a real limitation to good LLM output, and this workflow may work completely against it.
- A plan.md describing the project, main abstraction idea, end costumer, and so on is great; but it should be kept minimal and up-to-date with the repo.
- Block comments on top of source-files and functions are great, and already very useful to coding agents. I don't see a value to anything more than what is already typical best practice.
Git history is a bit annoying to navigate, but that may just be a tooling issue. I've long been bothered by the loss of the review history when merging a PR. Would actually be pretty cool to click on a row of code and see the commit messages that formed that row of code in a little sidebar, and the technical discussions that were behind it.
Functional safety development processes often demand code-review, technical design decisions, changes of plans, or intentional compromises; to be linked together with reference IDs in the code they effect. But the workflow for this is usually extremely manual and absolute misery. But a codebase made like this is like magic to read later.
I want to do something like that with git-bug (keeping track of prompt/conversation/review alongside normal commit), but unsure what the DX would be. Insights welcome :)
Some tools will automatically ignore commits in a .git-blame-ignore-revs file. Git itself can "blame --ignore-rev <hash>" or "blame --ignore-revs-file <file>" since version 2.23.
Though git-blame may fail or crash if blame.ignoreRevsFile is set but the file is missing (hence "config", not "config --global"). Since version 2.53, a configured ignoreRevsFile can be missing if the value starts with ":(optional)".
Yes and no. Git blame is great yes, but it's still rather crude. If three commits changed one condition; it only shows the top commit. Getting a full sense of the history of a function over time is far less ergonomic.
The tech and data-structure is there; but the common UX is not quite expressing the data in a sophisticated manner. It doesn't help that the default diff algorithm is rather crude as-well.
I am skeptical of adding anything but a brief description of the change, the reason for the change and possibly some explanation of non-obvious implementation choices to the commit message.
The reason is that the commit message log serves as an overview of the changes commited. That's what humans use it for, anyway: to get an idea of what happened since they last pulled, to help give an idea of where a regression might have been introduced and so on, at a glance. To that end, brevity is very useful.
My understanding is that chatbots used to perform such tasks will also benefit from brevity.
Well, at least in Git, the commit message already has two sections.
AFAIK, the first line is supposed to be the a very brief summary, while the other lines may contain additional information and can sometimes make up a pretty long text. Lots of tools make use of this convention and only show the first line if no detail information is needed.
Most tools that show the history only show the first line of each commit.
But I agree with you, this still assumes that long commit messages are rare and not that almost every commit has a huge message. Also, "long" doesn't mean you should put a novel in there.
I think long is fine if that's necessary to get a rough idea of what the change is about across. Discerning in the choice of what information to include is perhaps a better way to put it. In those terms we should consider how likely it is for prompts to be immediately useful information when browsing the commit history, and whether it can't instead be reduced to an informative summary.
As far as specifications for changes go, the diff itself is as good a spec as it gets. It unambiguously describes the exact change that was made. The prompt you give a chatbot to make that change is IMO something else. Maybe it's more fair to call that a specification of the work you wanted it to perform.
aDyslecticCrow · · focus · HN ↗
Cluttering the repo with out-dated, very wordy and quickly aging prompts will just confuse any agent tasked with looking at the repo in the future. Keeping context windows down is a real limitation to good LLM output, and this workflow may work completely against it.
- A plan.md describing the project, main abstraction idea, end costumer, and so on is great; but it should be kept minimal and up-to-date with the repo.
- Block comments on top of source-files and functions are great, and already very useful to coding agents. I don't see a value to anything more than what is already typical best practice.
xg15 · · focus · HN ↗
If prompts are specifications for a change of the system's behavior, then it seems natural to manage them as changes and not as resources.
This would also keep them in the right "historical context" of the repo and avoid the "prompt rot" you were talking about.
aDyslecticCrow · · focus · HN ↗
Functional safety development processes often demand code-review, technical design decisions, changes of plans, or intentional compromises; to be linked together with reference IDs in the code they effect. But the workflow for this is usually extremely manual and absolute misery. But a codebase made like this is like magic to read later.
[deleted] · · focus · HN ↗
[deleted]
ffsm8 · · focus · HN ↗
You'd consequently only need to implement your custom git gui and extension to visualize this information.
Maybe a good project for the next weekend? Just eg make a prototype tui in golang and see where you end up
jamietanna · · focus · HN ↗
michaelmure · · focus · HN ↗
chapterjason · · focus · HN ↗
mschuster91 · · focus · HN ↗
matijsvzuijlen · · focus · HN ↗
[deleted] · · focus · HN ↗
[deleted]
bulatb · · focus · HN ↗
aDyslecticCrow · · focus · HN ↗
The tech and data-structure is there; but the common UX is not quite expressing the data in a sophisticated manner. It doesn't help that the default diff algorithm is rather crude as-well.
boomlinde · · focus · HN ↗
The reason is that the commit message log serves as an overview of the changes commited. That's what humans use it for, anyway: to get an idea of what happened since they last pulled, to help give an idea of where a regression might have been introduced and so on, at a glance. To that end, brevity is very useful.
My understanding is that chatbots used to perform such tasks will also benefit from brevity.
xg15 · · focus · HN ↗
AFAIK, the first line is supposed to be the a very brief summary, while the other lines may contain additional information and can sometimes make up a pretty long text. Lots of tools make use of this convention and only show the first line if no detail information is needed.
Most tools that show the history only show the first line of each commit.
But I agree with you, this still assumes that long commit messages are rare and not that almost every commit has a huge message. Also, "long" doesn't mean you should put a novel in there.
boomlinde · · focus · HN ↗
As far as specifications for changes go, the diff itself is as good a spec as it gets. It unambiguously describes the exact change that was made. The prompt you give a chatbot to make that change is IMO something else. Maybe it's more fair to call that a specification of the work you wanted it to perform.