A graph starts from a question, and a hunch is a source - #26
Merged
Conversation
The documented shape began at `source`, which left two things unsaid and one thing wrong. WHAT A GRAPH IS FOR HAD NOWHERE TO LIVE. `graph.yaml: description` held the research question as prose, so nothing could cite it: a finding could not be traced back to the question it serves, and a graph with a second sub-question had nowhere to put it. `knoten init` now scaffolds `question-<name>.md` beside the gate example, and `question` joins the declared vocabulary. Everything else descends from it. `question` WAS IN THE WRONG PLACE. `viz.FLOW` listed it third — after `source` and `idea`, behind the two things that derive from it — so the column order contradicted the research order it exists to show. It goes first now, in both `viz.py` and the template's own legend. A SOURCE WAS DEFINED TOO NARROWLY. "External material the work starts from" excludes the case a lot of research actually begins in: somebody's own intuition. It is now "where the work came from — a paper, blogpost, dataset, search, or your own intuition", with the convention of writing `source-own-intuition` and citing it like any paper. That keeps one rule rather than two — an idea always names where it came from — and it makes an uncomfortable question answerable: how much of this graph rests on hunches rather than on having read anything? Verified end to end: init writes the question, the fresh graph validates, `question` is the leftmost column, and a hunch recorded as a source passes.
…e package A simplifier pass found that the headline claim of this branch was not true. THE REORDER DID NOT DELIVER QUESTION-FIRST. `roles()` sorted SHELVES ahead of everything, and a shelf is any type that is cited and never cites. A `source` an idea derives from, on a graph where nothing happens to cite the question back, is a shelf — so `source` overtook `question` and the column order contradicted the loop it exists to show. Reproduced both ways before fixing. A type FLOW names is now placed by FLOW whatever its edges look like; shelf/flow detection only decides where the types FLOW does NOT name go. AND THE TEST COULD NOT HAVE CAUGHT IT. Its fixture had no edges, so there were no shelves, so the rule that actually decides ordering never ran and `cols[0] == "question"` passed vacuously. It now builds the real chain — an idea deriving from a source, nothing citing the question — which is exactly the arrangement that failed. Also from the review: - TEMPLATE_QUESTION's closing paragraph was three lines of documentation — a fourth copy of a sentence already in SKILL, INSTRUCTIONS, README and SPEC — committed verbatim into every graph anyone creates, where it would outlive its own accuracy. One line now, in the register TEMPLATE_GATE already uses. - `knoten init` never named the file it just wrote, so the single most important next action was invisible on the onboarding surface. - README's `node_types` example was a stale copy of the template: no `question`, and the exact "external material" wording this branch set out to broaden. `test_docs` extracts that block but only checks it loads, so the drift sailed through. - The `source:` meaning was 141 chars, twice its longest sibling, and wrapped to four lines in a legend panel that is a definition list. The argument for writing hunches down belongs in the README paragraph, not in every graph's config. - `examples/llm-research` had no question node, so the shipped example contradicted the shipped doctrine. It has one now, and `knoten path` traces question -> hypothesis -> the gate that killed it, which is the whole reason the question is a node. - `build/lib/knoten/` was TRACKED: twelve files, a stale copy of the package still carrying the old FLOW order and no TEMPLATE_QUESTION. Pre-existing, but this branch widened the divergence, and grep in a codebase whose value is reading it in one sitting was returning two contradictory answers.
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.
The documented shape started at
source. That left two things unsaid and one thing wrong.The question had nowhere to live
graph.yaml: descriptionheld the research question as prose, so nothing could citeit — a finding could not be traced back to the question it serves, and a graph with a
second sub-question had nowhere to put it.
knoten initnow scaffoldsquestion-<name>.mdbeside the gate example, with prompts forwhy it matters and what would count as an answer, and
questionjoins the declaredvocabulary.
questionwas in the wrong place — a bug I shippedviz.FLOWlisted it third, aftersourceandidea: behind the two things thatderive from it. So the column order contradicted the research order it exists to display.
Fixed in
viz.pyandviz.html.A source was defined too narrowly
"External material the work starts from" excludes where a lot of research actually
begins — somebody's own intuition. Now:
with the convention of writing
source-own-intuitionand citing it like any paper. Thatkeeps one rule instead of two — an idea always names where it came from — and it makes
an uncomfortable question answerable: how much of this graph rests on hunches rather than
on having read anything?
The shape now
Documented in
SKILL.md, the MCPINSTRUCTIONS,README.mdandSPEC.md.Verified
266 passed, 6 skipped, plus a real walkthrough:knoten init demowrites the question,knoten validatepasses on the fresh graph,knoten indexlists both scaffolded nodes.New tests cover the scaffold,
questionbeing the leftmost column, and a hunch recorded asa source validating.