Condense SPEC.md - #29
Merged
Merged
Conversation
456 -> 402 lines, 3,599 -> 3,188 words. A smaller cut than the README's, and deliberately so: most of SPEC's length is evidence and recorded decisions rather than repetition, and deleting that would be deleting the reason the code is shaped this way. What came out was duplication and staleness. §8 stated the same ~2,340-token measurement TWICE — once under "The measurement" and again in the paragraph explaining the deletion — because the second was written when the surface was demoted and the third when it was removed, each appending rather than editing. One statement now, and the reversal reads as one argument instead of three layers of sediment. §5's table had two right-hand columns that paraphrased each other (`no_signal` = "the effect is not there" / "a signal that wasn't there") and re-printed two rule blocks that §6 already carries in full. It keeps the vocabulary and the argument for why the core must not enforce it; §6 keeps the rules. §6 merged two example rules that differed only in which key they demonstrated, and tightened the prose around the key table — which is the section's actual reference value and is untouched. §4's derivation subsection and §8.1 lost restatements, not content: both had grown a paragraph re-making a point the paragraph above already made. Two stale things fixed while in there. §11's open question 4 asked whether a closed `cause` vocabulary should become a rule primitive — `require_field_one_of` shipped some time ago and a second graph did want it, so it is struck through and answered like question 2 beside it. And §3's node-type paragraph had accumulated a run-on sentence across two edits.
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.
456 → 402 lines, 3,599 → 3,188 words.
A smaller cut than the README's 48%, and deliberately so. Most of SPEC's length is
evidence and recorded decisions — the prior-art table, the 2019 survey finding that no
research ontology models hypothesis death, the seven-hypotheses-six-died dogfood result —
and cutting those would delete the reason the code is shaped the way it is. What came out
is duplication and staleness.
What was actually redundant
§8 stated the same ~2,340-token measurement twice — once under "The measurement" and
again in the paragraph explaining the deletion. Each was written at a different moment
(demotion, then removal) and each appended rather than edited, so the section had become
three layers of sediment arguing one point. It now reads as one argument.
§5's table had two columns that paraphrased each other —
no_signalwas glossed as"the effect is not there" and "a signal that wasn't there" — and it re-printed two rule
blocks that §6 already carries in full. It keeps the vocabulary and the argument for why
the core must not enforce it; §6 keeps the rules.
§6 merged two example rules that differed only in which key they demonstrated. The key
table — the section's actual reference value — is untouched.
§4's derivation subsection and §8.1 lost restatements, not content: both had grown a
paragraph re-making the point the paragraph above already made.
Two stale things fixed in passing
causevocabulary should become a ruleprimitive.
require_field_one_ofshipped some time ago and a second graph did want it —struck through and answered, like question 2 beside it.
Verified
285 passed.test_docs.pystill extracts and executes every node and rules block fromSPEC against the real example graph — the merge of two rule examples into one is why the
count moved from 286.