docs: say which document kinds are skipped automatically and which are not - #15
Merged
Conversation
…e not Hand-checking 62 findings across 44 repositories: of the 14 that landed in a planning document - design notes, workstream records, ship plans, evidence logs, across five unrelated projects - every one was a false positive. Findings in reference documentation over the same run were right 35 of 37. The class was already named under Configuration, and adr/ and prd/ are already skipped on the path alone. What was missing is that a reader cannot tell which side of that line their own docs/designs/ or docs/workstreams/ falls on, and nothing in a report says. Both tables are generated from the behaviour, not from the source: migration-guide.md and migrations/ are judged, because the rule matches a whole path segment. Stated as one measurement rather than a law: it says what these 44 repositories did, and the split has not been reproduced on a corpus chosen after it was seen.
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.
docproofalready treats some documents as history without being told, and the Configuration section already names the class in prose. What a reader cannot tell is which side of that line their owndocs/designs/ordocs/workstreams/falls on - and nothing in a report says.This adds two tables under Configuration: what is skipped on the path alone, and what is still judged with the reason why.
Both tables were generated by running the predicate, not by reading the source, which changed two rows I would have written wrongly:
migration-guide.mdandmigrations/are judged, because the rule matches a whole path segment and neither of those is one.It also states what the omission costs, measured rather than asserted:
One of those fourteen was a completed cleanup checklist whose line read "Remove
docs/spec/tools/mdbook-spec/" - reported because the directory it asked you to delete had been deleted.Labelled as one measurement and not a law: it says what those 44 repositories did, and the split has not been reproduced on a corpus chosen after it was noticed.
Checked before opening:
docproofondocproofis clean (23 claims checked, nothing contradicted) and--show-skipsconfirms every new path in the tables was actually read and skipped with a reason, so that pass is sighted rather than blind. The outreach voice check caught three em dashes I had introduced into prose that had none; they are gone.