Add description authoring guide and update descriptions of higher level#55
Merged
Merged
Conversation
Jammjammjamm
approved these changes
Jul 29, 2025
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This is based on #52, but is replacing it because I condensed the guide into a single markdown file and clarified its purpose, and reran an LLM to update descriptions based on this. I have already manually verified each description that was updated; I do not believe further review of the descriptions are necessary.
One thing is clear to me though: this really needs to occur at test development time, as it is not very practical to change test descriptions by someone else or well after their initial creation. But i do think that this makes substantially better descriptions than what the test authors make.
This introduces a single guide: the description authoring guide, which was created by analyzing descriptions of US Core tests, as well as descriptions of existing IPS test descriptions, and formulating a set of best practices that a LLM (or human) can use to improve existing descriptions.
I then ran this on the higher levels of this repository: the test kit description, test suite description, and the higher levels of the testing 'tree'. I did not want to have an overwhelming update here, which is why I did not update all tests as is done in the other PR.
Whenever it did something incorrect, I had it update the description with what it did wrong so that it can avoid it in the future. The extra emphasis on understanding the code first before writing the description, and never assume anything about the spec but go out and read it if necessary, were put in there because of real issues that popped up. Saving that in the guidance seemed to help avoid the problem in the future.
This also does not change anything other than the descriptions, so this is a low risk PR.