Cut the README to what it is and how it works - #30
Merged
Conversation
296 lines -> 142; 2,105 words -> 763. It had become a manual with a README on top. What it is now: two paragraphs saying what knoten is and why it exists, one real dead node so you can see what a file looks like, the loop as a single command block, one rules example, and pointers out. Anyone who wants more has SKILL.md for the agent loop and SPEC.md for the design. What went, and where it lives instead: the research-loop diagram and edge directions (SKILL.md and SPEC §3-4, where an agent and a designer respectively will actually look); the query-vs-index argument, the frontier walkthrough, the gates record and the retraction example (SPEC §8.1 and §5); "Two readers, one file"; and the update/--field semantics, which SKILL.md already carries for the audience that needs them. The two claims worth keeping from the "why bother" section are now in the opening paragraphs where a reader arrives, rather than 250 lines below: a claim cannot be marked alive without citing a test it survived, and a dead end has to say what would reopen it. The node example and both yaml blocks stay, because test_docs executes them against the real example graph — the README's examples are the ones most likely to rot, so they are the ones worth keeping executable.
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
1 participant
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.
296 → 142 lines, 2,105 → 763 words. It had become a manual with a README on top.
What's left
SKILL.md,examples/,SPEC.md.What went, and where it lives instead
SKILL.md(agents) and SPEC §3–4 (designers)update/--fieldsemanticsSKILL.md, which serves the audience that needs themThe two claims worth keeping from the old "Why bother" section moved into the opening
paragraphs, where a reader arrives, rather than sitting 250 lines below: a claim cannot be
marked alive without citing a test it survived, and a dead end has to say what would
reopen it.
Kept executable
The node example and both yaml blocks stay, because
test_docs.pyruns them against thereal example graph. A README's examples are the ones most likely to rot, so they are
exactly the ones worth keeping executable.
284 passed— the count moved from 285 because two of the removed yaml blocks werethemselves parametrized doc tests.