Working with RDRs

RDR means Research, Design, Review. The name gives the order of the work. First you research. Then you design. Then the design is reviewed. The RDR document is a rendering of that work (Getting started, lesson 8): one readable file, written from what is in the stores. It changes when the work changes.

Why write one

A decision of any size is too big for one head, or for one Claude session. Without a written decision, three things happen. The goal moves while the code is written. Side problems take over. Three weeks later, nobody knows why a choice was made. An RDR puts the thinking before the code, so the code has a fixed target. Nexus also indexes every RDR, so the next decision on a similar subject finds this one.

What it is not

It is not a form to fill in. It is not a test plan. It is not a promise to a manager. A bug with one clear cause needs three sections: Problem, Root Cause, Fix. A design with real alternatives needs the full template. The length follows the size of the decision.

In practice, the usual problem is the opposite: an RDR grows. Sections are added one by one, each with a reason, until the document is longer than the decision needs. The skill an RDR needs is cutting, not filling. When Claude adds a section, ask which decision it serves. If the answer is none, remove it.

The lifecycle

An RDR does not begin with a template. It begins while you and Claude talk about a problem, when one of you sees that the problem is bigger than a quick fix. From then on, the conversation is the first draft.

When it starts

You describe a problem. Claude asks questions and proposes something. You disagree with part of it. After two or three exchanges, one of these is clear: there are several ways to do this, or the cause is not known yet, or other things depend on it. Then:

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. Claude writes the Problem Statement from the conversation so far, and lists the open questions from the conversation. Claude also writes a memory entry (Getting started, lesson 4) that names the RDR, so that later sessions know it exists. Nothing else is written yet. The other sections stay empty on purpose.

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 that has no written design. Say yes or no.

Right-size it now

Tell Claude how big the decision is. This decides how much of the template is used:

This is a bug with one cause. Problem, root cause, fix. Nothing else.

This is an architecture change. Use the full template, and we will need real alternatives.

Before you stop

An RDR of any size takes more than one session. When you stop for the day, when you change subject, or when you see the long-conversation warning, run /conexus:continuation first (Getting started, lesson 2 lists the three cases). The handoff names the RDR file, the open questions, and the first research to do. The next session continues from there.

Research is the R in RDR. It takes most of the time. It is not one step. It is a cycle: ask, read the answer, ask the next question. Each cycle adds findings to the RDR. Claude does the searching. You decide what to look at next.

A 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). The agent searches the knowledge store first, because an earlier RDR may already answer the question. Then it searches the code, then the web. When it finishes, Claude adds each finding to the RDR with /conexus:rdr-research add. Each finding has a tag:

The tags matter later. An Assumed finding that the design depends on is called a Critical Assumption. The gate (lesson 5) checks exactly those. This section is easy to leave empty. When it is empty, an unchecked belief can reach the design. If the design depends on something nobody checked, ask for it directly: "List the assumptions this design depends on, and mark which are verified."

The next cycle

Read the new findings, not the whole RDR. Something in them raises the next question. Ask it. 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?"

Three to six cycles is normal for a design of medium size. Some cycles take five minutes. Some take a whole session, when a finding needs a small program to be written and run.

Verify in batches

When several Assumed findings each need a small program to verify them, verify them together: one branch, one test run. Do not do them one at a time. A test run costs the same for one check or for five. Say: "Collect the assumptions that need a test program. Verify them together."

Between research cycles, and especially when the Proposed Solution starts to take shape, read the whole RDR and react to it. This is the rendering loop from Getting started, lesson 8, applied to one document. You do not edit the RDR line by line. You say what is wrong. Claude changes the document and the stores together.

Ask for a reading

Show me RDR <NUMBER> as it is now. The problem, what we know, the options, and which way the design is going.

Claude renders the current state. Read it as a reader, not as the author. Where do you stop understanding? Where does a claim have no finding behind it? Where does one option get one line and another option a full page?

React

Say what you see, in your own words. Examples of comments that move an RDR forward:

• "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."
• "I think the real constraint is <X>. Does the research support that?"

Claude changes the document. When the change is a fact (a number, a name, a decision), Claude also changes every other place where that fact appears, in the RDR and in memory. A fact has one home. If you see the same fact written in two different ways, that is a defect. Say so.

Bring in 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). The critic reads the RDR and reports what it finds, most important first. Claude fixes what is clearly wrong and shows you what needs your decision. This costs less than the gate (lesson 5), and you can do it as often as you want. Many RDRs get two or three critic readings before anyone thinks about a gate.

The gate is a formal check before acceptance. It asks three questions: is the document consistent, are the critical assumptions verified, and does an independent critique find anything that blocks. Not every RDR needs it. A small decision that the reading loop in lesson 4 has already tested can go from draft to accepted on that reading alone. Use the gate for decisions that are expensive to reverse: a database schema, a wire protocol, a migration. When you use it, give it a fixed number of rounds. Do not run it until it finds nothing. A critique always finds something. After the second round, it is cheaper to find the rest by building.

You say when

Run the gate on RDR <NUMBER>. Budget: two rounds.

Claude runs /conexus:rdr-gate. It makes three checks: the structure (are the required sections present and consistent), the assumptions (is every Critical Assumption verified or clearly accepted), and a critique by an independent agent. The result is PASSED, or BLOCKED with findings marked Critical, Significant, or Minor. Claude shows you the findings before it fixes anything.

Fixing what it finds

Claude runs /conexus:rdr-fix. It shows each finding with its place in the document, and then fixes them. Two rules apply. You will see Claude follow them:

• 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. New text is where the findings of the next round come from. A fact that needs support goes into a research finding first. The RDR sentence is then copied from that finding.

Then Claude runs the gate again. That is round two.

The budget

You give the signal to stop. Choose a word for it and use it. Without the signal, Claude continues, because each round produces findings, and findings look like work.

When it passes

Claude reports PASSED and the residuals, if there are any. If Claude fixed Significant findings during the pass, it stops and shows you the fixes before anything else. Read them. Then go to lesson 6.

Accepting is a decision, and it is yours. After it, the RDR is no longer a draft. It is the reference that the code is built against. Acceptance also starts the planning. In one chain, Claude turns the Implementation Plan into tracked tasks by phase, checks the plan, and adds detail to the tasks. Then the build can run over many sessions without losing the thread.

Accept, and the plan follows

Accept RDR <NUMBER>.

Claude runs /conexus:rdr-accept. The status becomes accepted, and memory records it. Then, because the RDR has an Implementation Plan, Claude asks one question: build the tasks now? The default is yes. Say yes, and the rest happens without more input from you, in this order:

1. The planner agent turns each phase of the Implementation Plan into tasks in the bd task tracker. The tasks have dependencies between them, and all of them belong to one epic that names the RDR.
2. The plan audit checks those tasks against the code as it is today: do the files exist, is the order possible, does the plan assume anything that the code contradicts.
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 finding from the audit that applies.

Then Claude shows you the task tree. You do not start the planner, the audit, or the enrichment yourself. They are the second half of accepting.

Say no when the RDR has nothing to build, for example a decision that only changes a rule, or when you want to plan later. You can run the planning chain later on its own with /conexus:create-plan.

The plan audit has the same budget rule as the gate: one round, two at most. A plan that is audited many times is a plan that nobody has tried to build.

Read the tree, not the tasks

Look at the phases and the dependencies. Is the first phase the one that proves the design works, or only the easiest one? It should be the one that proves the design. Is there a phase that produces nothing visible? Ask why. Then say go, or ask for changes.

The build takes days or weeks, in many sessions. Two things hold it together: the continuation at the end of every session, and the phase review at the end of every phase. The RDR is the fixed reference during the whole build. This lesson is about the rhythm, not about writing code.

A session in the build

1. Start the session by pasting the continuation from the last session. Claude reads it, checks the branch, and takes the next ready task.
2. Claude implements the task. The plugin tells it to write the test first, then the code, then ask for a review.
3. 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.
4. Claude closes the task. The task tracker now knows what is done. Memory records any decision made on the way.
5. When you stop for the day, change subject, or see the long-conversation warning: /conexus:continuation first, then stop.

You are there for the decisions and not for the typing. A useful habit: at the start of each session, before you paste the continuation, ask "Where are we on RDR <NUMBER>?" Compare the answer with the continuation. They should agree.

The end of a phase

Phase <N> looks done. Run the phase review.

Claude runs /conexus:phase-review-gate. It reads the Approach section of the RDR from top to bottom. It lists every concrete thing that the Approach says this phase delivers. For each one, it finds the closed task that delivered it. A thing named in the Approach with no task is one of three cases: it was built somewhere else (Claude shows where), it was moved to a named later task, or it is missing. Missing means the phase is not done. This check stops the scope from shrinking quietly, one small omission at a time.

Code review and test validation cannot find this. 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

Small things are different. A file name that changed, a detail that the Approach did not specify: note those in the task and in memory, not in the RDR. The question is whether the decision changed.

Closing is the last decision, and it is yours. It does three things. It settles every task that is still open. It records what the build taught. It moves the RDR into the knowledge store, so that the next decision finds it.

Before you close

RDR <NUMBER> is built. What is still open under it?

Claude lists every task under the RDR's epic that is not closed: open, deferred, or blocked. For each one, you decide: close it because it is done, move it to a named later piece of work, or keep the RDR open until it is done. Claude must not close a blocking task only to pass the gate. If it proposes that, refuse.

Close

Close RDR <NUMBER>, implemented. Write the post-mortem.

Claude runs /conexus:rdr-close. The status becomes closed. If you asked for it, Claude writes a short post-mortem: what the build changed compared with the plan, what took longer, and what was learned. Then Nexus indexes the RDR into the knowledge store. Memory records the close.

A post-mortem is worth writing when the build taught something that the RDR did not predict. When it did not, the close is only a status change, and that is correct.

What remains

The RDR is now part of the knowledge store. The next time you or Claude research a similar question, in this project or in another project that shares the store, the search finds it. The research agent reads it before it reads the web. This is the purpose of the whole cycle. One RDR is a decision. Many RDRs are a memory of how the project thinks.