Skip to content

docs: say which document kinds are skipped automatically and which are not - #15

Merged
melbinjp merged 1 commit into
mainfrom
docs/skipped-automatically
Aug 18, 2026
Merged

docs: say which document kinds are skipped automatically and which are not#15
melbinjp merged 1 commit into
mainfrom
docs/skipped-automatically

Conversation

@melbinjp

Copy link
Copy Markdown
Owner

docproof already 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 own docs/designs/ or docs/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.md and migrations/ 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:

Hand-checking 62 findings across 44 repositories: of the 14 that landed in a document describing a decision or a piece of work rather than the present tree, every single one was a false positive. Findings in reference documentation over the same run were right 35 times out of 37.

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: docproof on docproof is clean (23 claims checked, nothing contradicted) and --show-skips confirms 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.

…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.
@melbinjp
melbinjp merged commit a148cbb into main Aug 18, 2026
21 checks passed
@melbinjp
melbinjp deleted the docs/skipped-automatically branch August 18, 2026 23:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant