mehdiforoozandeh crux-rd — the design document a node cannot hold
crux caps a node's prose at 400 words. That cap exists because nodes measured in the thousands of words stopped being readable by the PI they exist to serve. But a cap with no outlet just makes prose denser. This is the outlet.
An RD is where design detail goes to be readable, not to hide. The node's TL;DR must still stand alone: a reader who never opens the RD still knows what is being asked and what would settle it. If moving text into an RD makes the node unintelligible, the move was wrong.
When you are invoked
Only when asked. This skill ships disable-model-invocation: true and means it. The
design being written up lives in the conversation that just happened with the PI — that
is the whole reason this is a skill and not an agent. From a cold start you would either
restate the node or re-derive the design badly.
So: no interview, no research phase, no "shall I write this up?" offered unprompted. When the PI says the design has settled, you synthesize what was already discussed.
The write-vs-skip filter — apply this before writing anything
Without an explicit filter, every node grows an RD, and the vault has simply moved its bloat one directory over. An RD is warranted when at least one of these holds:
- The design would exceed the 400-word prose cap on its own. Not the node — the design.
If the whole thing fits in
## Idea / Hypothesisinside budget, it belongs there. - The design makes a choice a reader would otherwise re-litigate. There is a rejected alternative worth recording. Research reasoning lives in the branch that was not taken, and it is the half that gets lost.
- The design carries a known distortion that must travel with every result. A pooling scheme that biases small strata, an attenuation you accept, a proxy that is not the thing. If a reader of the findings needs to know it, it has to be written somewhere durable.
Explicitly not warranted: a hypothesis whose design is its verifiables. That is the common case. Pre-registered checks with a metric, a baseline and a threshold are already a complete design, already structured, and already exempt from the cap. Writing an RD for one adds a file and no information.
When the filter says skip, say so and stop. "That design is its verifiables — it does not need an RD" is a correct, complete answer.
Writing one
crux rd <node-id> "<title>" # a question or a hypothesis; the project root and syntheses do not carry RDs
That creates rd/<slug>.md and writes the RD:: backlink into the node, beside Parent::.
Then you fill the template's sections:
| section | what goes in it |
|---|---|
| Context | what forced this design — the constraint, the finding, the question |
| Out of scope | an explicit fence. What this design deliberately does not cover, binding on the node and its children |
| Design | the substance |
| Considered options | the alternatives, and why each lost |
| Consequences and known distortions | what this gets wrong on purpose, and what must travel with every result |
| Supersedes | the chain (forward only — see below) |
Two habits worth keeping. Write for a reader who was not in the conversation — that is the person the RD exists for, and it is you in six weeks. And after writing, re-read the node: if its TL;DR no longer stands alone, move a sentence back.
An active RD is never amended in place
This is the rule the whole layer is built around. When a design changes:
crux rd <node-id> "<new title>" --supersedes <old-slug>
That writes a new RD, flips the old one to superseded, and re-points the node. The chain
is the reasoning history — what was believed, and what replaced it. Editing the live document
instead destroys exactly the record that makes a design reviewable, which is the failure this
layer was built to fix: a node body treated as the only durable record accumulates
AMENDED markers until nobody can tell what the design currently is.
The engine does not police this. crux validate checks that the link resolves, that the
two ownership records agree, that only one design is live, and that the chain is acyclic — it
does not detect an edit to a superseded RD, by design. git log -p rd/<slug>.md is the
audit trail, the same call crux already makes for a node's decision history. So the
discipline is yours: if you find yourself editing a superseded file, stop and supersede
instead.
The same rule you already follow for nodes applies here: on a PI ruling, edit the node; the diff is the history. For an RD, the ruling writes a new document.
What an RD is not
- Not evidence. It never enters the roll-up, never moves
ledger_counts, never trips the review gate. Verdicts come from verifiables; an RD is a document. - Not a work list. Open work items are a taskhub concern, not a design document. An RD that accumulates TODOs is turning into the node it was meant to relieve.
- Not a changelog. Decision history goes to git.
- Not literature. Background, prior methods and baselines are the wiki's job
(
crux-wiki), and the flow is one-way: the wiki may never cite an RD or a tree node. An RD may cite the wiki freely — grounding a design in prior work is the flow rule working.
Checking your work
crux validate --check=rd # link resolves · ownership agrees · one live design · chain acyclic
crux validate # the whole vault, RD lint included
If a node is still over the 400-word cap after you have moved its design out, the remainder is either work items or history — and neither belongs in the node either.