rdr-create

---
name: rdr-create
description: Use when starting a new research-design-review document to think through a technical decision
effort: medium
---

# RDR Create Skill

## When This Skill Activates

Prose follows `resources/rdr/REGISTER.md`: written for a smart reader who may not know this project's jargon; simplified, never simplistic; jargon defined on first use. Each lifecycle stage has a named reader there; write the RDR for the create-stage reader.

- User says "create an RDR", "new RDR", "start an RDR"
- User invokes `/conexus:rdr-create`
- User wants to think through a technical decision — before, during, or after building

## Inputs

Prompt the user for:
- **Title** (required): e.g., "Bulk PDF Indexing with OCR Support"
- **Type** (optional, default: Feature): Feature | Bug Fix | Technical Debt | Framework Workaround | Architecture
- **Priority** (optional, default: Medium): High | Medium | Low
- **Related issues** (optional): bead IDs or URLs

## Behavior

### Step 0: Resolve RDR directory

Read the RDR base directory from `.nexus.yml` `indexing.rdr_paths[0]`; default `docs/rdr`:

```bash
python3 -c "
import os, re, sys
f = '.nexus.yml'
if not os.path.exists(f): print('docs/rdr'); sys.exit()
t = open(f).read()
try:
    import yaml; d = yaml.safe_load(t) or {}; paths = (d.get('indexing') or {}).get('rdr_paths', ['docs/rdr']); print(paths[0] if paths else 'docs/rdr')
except ImportError:
    m = re.search(r'rdr_paths[^\[]*\[([^\]]+)\]', t) or re.search(r'rdr_paths:\s*\n\s+-\s*(.+)', t)
    v = m.group(1) if m else ''; parts = re.findall(r'[a-z][a-z0-9/_-]+', v)
    print(parts[0] if parts else 'docs/rdr')
" 2>/dev/null || echo "docs/rdr"
```

Use this value as `RDR_DIR` throughout all steps below (wherever `docs/rdr` appears).

### Step 1: Bootstrap (first use only)

If `$RDR_DIR` does not exist:
1. Create `$RDR_DIR/` and `$RDR_DIR/post-mortem/` directories
2. Copy RDR template from `$CLAUDE_PLUGIN_ROOT/resources/rdr/TEMPLATE.md` to `$RDR_DIR/TEMPLATE.md`
3. Copy post-mortem template from `$CLAUDE_PLUGIN_ROOT/resources/rdr/post-mortem/TEMPLATE.md` to `$RDR_DIR/post-mortem/TEMPLATE.md`
4. Create `$RDR_DIR/README.md` from `$CLAUDE_PLUGIN_ROOT/resources/rdr/README-TEMPLATE.md`

If `$CLAUDE_PLUGIN_ROOT` is not available, use the templates inline (they are embedded below in the Templates section).

> **Gap convention** (enforced at `/conexus:rdr-gate` Layer 1 for post-65 RDRs): the `## Problem Statement` (or `## Problem`) section must contain one or more `#### Gap N: <title>` headings (regex: `^#{3,5} Gap \d+:`). Fill these in during drafting — the template scaffolds `Gap 1` and `Gap 2` placeholders. Replacing the Problem Statement with free-form prose and removing the gap headings will fail the gate. Authors can override with `/conexus:rdr-gate <id> --skip-gaps` when the gap structure truly does not fit (audit-trail escape only; prefer adding real gap headings).

### Step 1b: Ensure the prose register is present (every invocation)

If `$RDR_DIR/REGISTER.md` does not exist, copy it from `$CLAUDE_PLUGIN_ROOT/resources/rdr/REGISTER.md`. This runs on EVERY invocation, not only at bootstrap: repos onboarded before the register existed never re-run bootstrap, and the pointer lines across the rdr-* surfaces assume the file is there. Idempotent: present means untouched.

### Step 2: Assign ID

Run `nx rdr preamble rdr-create`. Take the `Next ID:` it prints; it also prints
`ID style detected:` for the repo's filename convention. It skips numbers held by
any branch, another worktree or a T2 record and lists them; if it says the holder
scan is incomplete, check those sources yourself before trusting the number.

Before Step 3, confirm the number is free in T2: `memory_put` upserts by (project,
title), so writing a held number's record silently replaces it (nexus-3piej). Call
`mcp__plugin_conexus_nexus__memory_get(project="{repo}_rdr", title="{NNN}")`. Only a
"not found" answer means free. Any record, and an "Ambiguous title prefix" answer
(rows such as `{NNN}-research-1` exist), means another RDR holds the number: re-run
the preamble and take a higher number, then check again.

Never hand-scan with a fixed glob. `[0-9][0-9][0-9]-*.md` requires a filename to
begin with three digits and matches none of nexus's 217 `rdr-NNN-*.md` files, so
it falls through to `001` and collides with RDR-001.

Preamble unavailable: extract from the real filenames, and start at `001` only if
that returns nothing.
```bash
ls "$RDR_DIR" | sed -nE 's/.*([0-9]{3}).*\.md/\1/p' | sort -n | tail -1
```

Derive project prefix from repo name:
```bash
basename $(git rev-parse --show-toplevel) | tr '[:lower:]' '[:upper:]' | tr -cd '[:alnum:]' | head -c 3
```
Example: `nexus` → `NEX`, `arcaneum` → `ARC`, `nx-tools` → `NXT` (hyphens stripped)

### Step 3: Create RDR file

Create `$RDR_DIR/NNN-kebab-case-title.md` from the template with these metadata fields pre-filled:
- **Date**: today's date (YYYY-MM-DD)
- **Status**: Draft
- **Type**: user's choice
- **Priority**: user's choice
- **Related Issues**: user's input (if any)

Replace `[NUMBER]` with the assigned ID and `[TITLE]` with the user's title.

### Step 4: Write T2 record

Only for a number Step 2 confirmed free in T2:

mcp__plugin_conexus_nexus__memory_put(content="id: NNN\nprefix: PREFIX\ntitle: User's Title\nstatus: draft\ntype: Feature\npriority: Medium\ncreated: YYYY-MM-DD\ngated: \nclosed: \nclose_reason: \nsuperseded_by: \nsupersedes: \nepic_bead: \narchived: false\nfile_path: $RDR_DIR/NNN-kebab-title.md", project="{repo}_rdr", title="{NNN}", tags="rdr,{type}"  # omit ttl (memory_put's ttl is int|None; permanent by omission)

### Step 5: Regenerate README index

Read all T2 records for `{repo}_rdr` project via memory_get tool: project="{repo}_rdr", title="". If T2 is empty (first create before T2 write completes), also scan filesystem frontmatter. Generate the index table and update `$RDR_DIR/README.md`.

### Step 6: Stage files

```bash
git add $RDR_DIR/NNN-kebab-title.md $RDR_DIR/README.md
```

If bootstrap ran, also stage: `$RDR_DIR/TEMPLATE.md`, `$RDR_DIR/post-mortem/TEMPLATE.md`
If Step 1b copied the register, also stage: `$RDR_DIR/REGISTER.md`

### Output

Print:
```
Created RDR PREFIX-NNN: "Title"
File: docs/rdr/NNN-kebab-title.md
Status: Draft

Next: Fill in Problem Statement and Context, then use /conexus:rdr-research to add findings.
```

## Success Criteria

- [ ] RDR directory resolved from `.nexus.yml` `indexing.rdr_paths[0]` (default `docs/rdr`)
- [ ] RDR file created at `$RDR_DIR/NNN-kebab-title.md` with correct metadata
- [ ] Sequential ID assigned (no collisions with existing RDRs)
- [ ] T2 record written to `{repo}_rdr` project with all required fields
- [ ] `$RDR_DIR/README.md` index regenerated with new entry
- [ ] Files staged via `git add`
- [ ] Bootstrap completed on first use (template and directory structure)

## Agent-Specific PRODUCE

This skill produces outputs directly (no agent delegation):

- **T3 knowledge**: Not produced at create time (archival happens at `/conexus:rdr-close`)
- **T2 memory**: RDR metadata record via memory_put tool: project="{repo}_rdr", title="{NNN}", tags="rdr,{type}" (omit `ttl`; permanent by omission)
- **T1 scratch**: Working notes during creation via scratch tool: action="put", content="RDR NNN: scaffolding", tags="rdr,create" (optional, for tracking multi-step creation)
- **Filesystem**: `docs/rdr/NNN-kebab-title.md`, updated `docs/rdr/README.md`

**Session Scratch (T1)**: Use scratch tool for ephemeral working notes if the creation involves multiple prompts or complex ID assignment. Flagged items auto-promote to T2 at session end.

## Does NOT

- Create beads (that happens at `/conexus:rdr-close`)
- Run validation (that happens at `/conexus:rdr-gate`)
- Commit (user decides when to commit)
- Run `nx index rdr` (user can do this manually or it happens at gate/close)