Working with RDRs
An RDR is a decision that you and Claude shape together: the problem, what research found, the options, and the choice. This page follows one RDR from the conversation where it starts to the day you close it.
Without a record, the reasoning behind the code disappears into chat history. An RDR is that record. You and Claude both read it, change it, and steer by it. When the build proves one wrong, you abandon it and write the next. The chain of RDRs becomes the record of how the work went. RDR has the full reasoning.
Words in <ORANGE CAPITALS IN ANGLE BRACKETS> are placeholders for your own subject, and the prompts are examples, so your own words work the same. The page uses two ideas from Getting started: continuations (lesson 6) and renderings (the appendix).
How it works. Both of you steer. You bring the first ideas, direct the research, and edit the RDR yourself. Claude searches and drafts, and it objects when the evidence shows that an idea will not work, whether the idea is yours or its own. Each exchange leaves a finding, a cut, or a changed option in the RDR, and the next exchange starts from there. At acceptance you say "this is what we build against", and at close you say "this is what happened".
Spend most of your time on research and design. The plan follows from the design, and the code follows from the plan, so a flaw in the design shows up in the code. Where the design leaves a question open, the planner answers it with its own choice, and you find that choice later in the code. Keep iterating until the design is the one you want built.
Start an RDR
An RDR begins in conversation, when you and Claude see that a problem is bigger than a quick fix. From then on the conversation is the first draft.
When it starts
You describe a problem, Claude proposes something, and you disagree with part of it. When there are several ways to do it, the cause is unknown, or other things depend on it, say:
This is bigger than a patch. Let's make it an RDR. Start from what we just discussed.
Claude creates the file with /conexus:rdr-create. The file gets the next number, the header fields, the section headings, and the status draft. The sections stay empty, and the skill ends by telling you to fill in the Problem Statement and Context next. It also writes a memory entry (Getting started, memory) that names the RDR, so later sessions know it exists.
Claude may also propose the RDR: "This has three possible designs. Do you want an RDR?" The plugin tells Claude to ask before it builds anything with no written design.
Choose the size now
Tell Claude how big the decision is. The gate checks every RDR for the same sections, so size changes how much you write in each, not which sections exist. A bug with one clear cause keeps each section to a few lines. A design with real alternatives fills them in fully.
This is a bug with one cause. Keep every section short.
This is an architecture change. Use the full template, and we will need real alternatives.
The usual problem is too much text, not too little. When Claude adds a section, ask which decision it serves, and remove it if the answer is none.
Before you stop
An RDR of any size takes more than one session. When you stop for the day, change subject, or see the long-conversation warning, run /conexus:continuation first (Getting started, lesson 6 lists the three cases). The handoff names the RDR file, the open questions, and the first research to do, and the next session continues from there.
Investigate further
- Ask Claude to show the new file: "Show me RDR <NUMBER> as it is now." At this stage it is short, and that is correct.
- The brainstorming gate: why Claude asks before it builds anything without a written design.
Research, read, and react
Research is a cycle: ask, read the answer, and ask the next question. Each cycle adds findings to the RDR. You direct it: what to look at, which finding to doubt, and when a question is answered.
A research cycle
Research how <THE THING THE DECISION DEPENDS ON> actually behaves. Check our code, our knowledge store, and the outside sources. Add what you find to RDR <NUMBER>.
Claude starts the research agent (/conexus:research), which searches the knowledge store, your code, and the web. A search covers earlier RDRs only when it includes the rdr collections, so name an earlier RDR when you want it. Claude adds each finding to the RDR with /conexus:rdr-research add, and each finding has a tag:
| Tag | Meaning |
|---|---|
| Verified | Confirmed by reading the code, or by a small program that was run. |
| Documented | Supported only by documentation. Not checked against the real system. |
| Assumed | Believed, but not checked. The design may depend on it. |
The gate (lesson 3) counts findings by tag and flags the high-risk ones, which are Assumed findings with nothing but documentation behind them. The assumptions section is easy to leave empty, and then an unchecked belief can reach the design. Ask directly: "List the assumptions this design depends on, and mark which are verified."
Read the new findings rather than the whole RDR, because something in them raises the next question. Typical next questions:
- "That finding is Assumed. Can you verify it? Write a small test or read the source."
- "You found that <X>. Does that exclude option <B>?"
- "We did something like this in RDR <OLDER NUMBER>. What did we learn there?"
- "Measure it. How long does <THE OPERATION> take now?"
Keep going while each answer raises a question that matters to the design. When several Assumed findings each need a small program, verify them together on one branch with one test run.
Alternatives appear here, not later. Have Claude write each option into Alternatives Considered as soon as it is clear, with the reasons for and against it.
Read it and react
Between cycles, and especially when the Proposed Solution becomes clear, read the whole RDR as a new reader would. This is the rendering loop from the Getting started appendix, applied to one document.
Show me RDR <NUMBER> as it is now. The problem, what we know, the options, and which way the design is going.Look for where you stop understanding, a claim with no finding behind it, and an option that gets one line while another gets a page. Then say what you see in your own words. Comments like these improve an RDR:
- "The problem statement is about performance, but the findings are all about correctness. Which is it?"
- "Option B is rejected in one sentence. Give it the same space as option A."
- "That number in the approach, where does it come from? I do not see a finding for it."
- "This section repeats the last one. Cut it."
You can also edit the file directly and tell Claude, so that it changes the same fact in memory. A fact has one home, so the same fact written two different ways is a defect. Point it out, and Claude changes the fact everywhere it appears.
Ask a second reader
Have the critic read RDR <NUMBER> before I do. Structural problems, unsupported claims, missing alternatives.Claude starts the critic agent (/conexus:substantive-critique), which reports what it finds, most important first. Claude fixes what is clearly wrong and shows you what needs your decision. A critic reading costs less than the gate, and you can ask for one as often as you want. Many RDRs get several before anyone thinks about a gate.
While the status is draft, nothing is final. Change the problem statement, remove an option, or split the RDR in two when research shows two decisions inside one. Before you ask for the gate, check two things. You can explain the design in your own words, and the RDR answers every issue you raised. Most of the value of an RDR is made here.
Investigate further
- Ask Claude: "Which findings in RDR <NUMBER> are still Assumed, and which of those does the design depend on?"
- Ask for a rendering for a reader who was not in the conversation: "Render RDR <NUMBER> for a new team member." Gaps that you no longer notice become visible.
- The research skill and evidence classification: how findings are recorded, verified, and tagged.
- The critic agent: what it looks for.
Run the gate
The gate is the formal check before acceptance, and an RDR cannot be accepted until its gate has passed. The reading in lesson 2 finds most problems first, which keeps the gate short.
You say when
Run the gate on RDR <NUMBER>.Claude runs /conexus:rdr-gate, which makes three checks. The structure check asks whether the required sections are present and consistent. The assumptions check asks whether every high-risk finding is verified or clearly accepted. The third check is a critique by an independent agent. The result is PASSED, or BLOCKED with findings marked Critical, Significant, or Observation, and Claude shows you the findings before it fixes anything.
Fixing what it finds
Claude runs /conexus:rdr-fix, which shows each finding with its place in the document and then fixes it under two rules:
- A fix changes a fact, not one sentence. If a number was wrong, every place where that number appears changes, including memory.
- A fix adds no new explanation, because new text is where the next round's findings come from. A fact that needs support goes into a research finding first, and the RDR sentence is copied from that finding.
Then Claude stops. It does not run the gate again by itself, because you decide when the next round happens. Ask for it when you want it.
The budget
Rounds 1 and 2 block on any Critical finding. Round 3 is yours to ask for, and from round 3 only a ship-blocker blocks. Every other Critical and Significant finding becomes a residual, and at accept you name a commit or a bead for each one. Accept refuses until you do.
Why the budget exists. After two rounds, new findings are usually in text that the previous fix added, not in the design. RDR gives the full reasoning.
When it passes
Claude reports PASSED and any residuals. Read the fixes Claude made to Significant findings before you accept, and then go to lesson 4.
Investigate further
- The gate skill: the three checks in detail.
- The fix skill: the fix rules, and why a fix commit adds no new text.
Accept, and the plan follows
Accepting is your decision. After it, the RDR is the reference that the code is built against. Acceptance also starts the planning, so the build can run over many sessions and each session knows where the work is.
Before you accept, ask "What will the plan have to decide that the RDR does not say?" Settle those points while the RDR is still a draft.
What acceptance runs
Accept RDR <NUMBER>.Claude runs /conexus:rdr-accept. If the gate recorded residuals, Claude first asks for a commit or a bead for each one, and accept refuses without them. Then the status becomes accepted and memory records it. When the Implementation Plan has two or more steps, planning is mandatory. With fewer, Claude asks whether to build the tasks now, and the default is yes. The planning happens in this order:
- The planner agent turns each phase of the Implementation Plan into tasks in the
bdtask tracker. The tasks have dependencies between them, and all of them belong to one epic that names the RDR. - The plan audit checks those tasks against the code as it is today: do the files exist, is the order possible, and does the plan assume anything that the code contradicts. It blocks planning in rounds 1 and 2 and can no longer block from round 3.
- Task enrichment adds to each task what a builder needs: the files to change, the tests to run, the rules from the RDR, and any audit finding that applies.
Then Claude shows you the task tree. You do not start the planner, the audit, or the enrichment yourself, because they are the second half of accepting.
With fewer than two steps you can say no, for example for a decision that only changes a rule, or to plan later. You can run the planning chain on its own later with /conexus:create-plan.
Read the tree, not the tasks
Look at the phases and the dependencies. The first phase should prove that the design works, not only be the easiest one. A phase that produces nothing visible needs a reason. Then say go, or ask for changes.
Investigate further
- Ask Claude: "Show the task tree for RDR <NUMBER>, and which task is ready to start."
- The planning skill: how phases become tasks.
Build it across many sessions
The build takes days or weeks over many sessions. Two things connect the sessions: the continuation at the end of every session, and the phase review at the end of every phase. The RDR stays the fixed reference for the whole build.
A session in the build
- Start the session by pasting the continuation from the last session. Claude reads it, checks the branch, and takes the next ready task.
- Claude implements the task. The plugin tells it to write the test first, then the code, and then to ask for a review.
- For the review, Claude starts two reviewer agents: one for the code, and one critic for the fit with the design. Claude fixes what they find and shows you the rest.
- Claude closes the task, so the task tracker knows what is done. Memory also records any decision made during the work.
- End the session with
/conexus:continuation, as in lesson 1.
Your part in the build is steering. You question a choice and notice when the code no longer follows the design. You also say when something feels wrong, often before a review would find it. At the start of each session, before you paste the continuation, ask "Where are we on RDR <NUMBER>?" The answer and the continuation should agree.
The end of a phase
Phase <N> looks done. Run the phase review.Claude runs /conexus:phase-review-gate. It lists every numbered item in the RDR's Approach. Each item needs a pointer: the closed task that delivered it, or none when the item is deliberately out of scope for this phase. An item with no pointer is missing, and the phase is not done until it has one. This is a checklist that Claude walks with you, not an enforced gate, because nothing blocks the close. It exists to catch scope that shrinks quietly, one small omission at a time.
Code review and test validation cannot find this, because they check what was built. Only a comparison of the RDR with the tasks checks what was not built.
When the build proves the RDR wrong
Do not rewrite the decision. If a phase shows that a decision does not work, say so. Have Claude mark the RDR abandoned or superseded, and start a new RDR with what was learned. The new one is short, because most of the research is still valid. The old RDR stays as the record of what was believed and why. Findings and revision-history lines are recorded in an accepted RDR, but its decision text stays as it was.
A file name that changed, or a detail that the Approach did not specify, goes into the task and into memory, not into the RDR.
Status and code are two facts. An RDR's status says what was decided and says nothing about whether code exists. A day of work on tools or documents around an RDR can look like a day of building it in a status report. Ask at any time: "Does RDR <NUMBER> have code yet, and on which branch?" Claude should answer that in one sentence in every status report, unasked.
Investigate further
- The phase review gate: how the comparison works and why it exists.
- Ask Claude, mid-build: "What does the Approach of RDR <NUMBER> promise that has no task yet?" Ask this before the phase review, not after.
Close it
Closing is the last decision, and it is yours. It settles every open task and records what the build taught.
Before you close
RDR <NUMBER> is built. What is still open under it?Claude lists every task under the RDR's epic that is open or in progress. For each one, you close it as done or move it to a named later piece of work. Otherwise you keep the RDR open, or confirm that you close it anyway. Claude must not close a blocking task only to pass the gate, and if it proposes that, refuse.
Close
Close RDR <NUMBER>, implemented.Claude runs /conexus:rdr-close. An automatic critic reads the RDR first. If it finds significant issues, Claude cannot close the RDR as Implemented unless you give a reason to override. Then Claude writes the post-mortem: what the build changed compared with the plan, what took longer, and what was learned. It checks the open tasks, sets the status to closed, and records the close in memory.
If you close an RDR as reverted or abandoned, Claude offers a post-mortem instead of writing one. Both reasons set the status abandoned, and the reason stays in memory and in the post-mortem.
What remains
The RDR file is in its rdr collection from the first nx index repo after you write it, drafts included. Closing adds the post-mortem to the knowledge store, and it re-indexes the RDR only if the close changed its text. A later research question finds both when its search includes the rdr collections. One RDR is a decision, and many RDRs are a memory of how the project thinks.
Investigate further
- After a close, ask Claude to research a subject near the RDR's subject, with the
rdrcollections included, and watch it find the RDR. - The close skill: the task gate and the post-mortem template.
- The Nexus RDR index: every RDR of the project with its status. Choose a closed one and read its post-mortem.
Appendix: the statuses
RDR means Research, Design, Review, which is the order of the work. The file is a rendering of that work (the Getting started appendix), and its status says where the decision stands.
The six statuses and how they change
| Status | Meaning | It can move to |
|---|---|---|
| draft | Under discussion. Change it as much as you want, and do not treat it as a decision yet. | accepted when you accept it. deferred, superseded or abandoned. closed without acceptance, only with a reason, for a decision that shipped without the gate. |
| accepted | You accepted it. This is now the design, and code can start. | closed when you close it. deferred, abandoned, or superseded. |
| deferred | Parked. It can return, but only to draft. | draft, superseded, or abandoned. |
| closed | Built and shipped. The RDR is now a historical record. | superseded. |
| superseded | Replaced by a named later RDR. | nothing. |
| abandoned | It will not be built. The file stays as the record. | nothing. |
Further reading
- RDR: the full template and the reasoning behind it.
- RDR lifecycle rules and the plugin README.
- Decisions as indexed data: how RDRs sit between people and LLMs. How I actually use Nexus: the developer and the agents working from one store.