crux-rd

name	crux-rd
description	Write the Requirements Document for a crux node — the design detail that does not fit, and should not fit, inside a 400-word question or hypothesis. An RD is one immutable design document per node, living in `rd/` beside the tree, linked from the node, outside the roll-up: the estimand and its bound, the probe ladder, the negative control, the known distortion that must travel with every result. You do not interview and you do not re-derive — you write up the design that has just been settled in conversation with the PI, and you apply the write-vs-skip filter that stops every node from growing one. A design change is never an amendment: it is a new RD that supersedes the old, and the chain is the reasoning history. Invoke explicitly — the PI decides when a design has settled.
license	MIT
disable-model-invocation	true
metadata	{"author":"Mehdi Foroozandeh","version":"1.0","spec":".spec/07-rd-layer.md","requires":"the crux skill, installed as a sibling of this one (shares its engine at <crux skill>/scaffold/)","notice":"Borrows ADR mechanics (immutability, supersession, an explicit write filter); no third-party code."}

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:

1. The design would exceed the 400-word prose cap on its own. Not the node — the design. If the whole thing fits in ## Idea / Hypothesis inside budget, it belongs there.
2. 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.
3. 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.