rdr

Recommendation Decisioning Records (RDRs)

RDRs are specification prompts built through iterative research and refinement.

Unlike ADRs which document decisions already made, RDRs evolve during planning as the problem statement becomes more refined through research and exploration and alternatives emerge with one as the best option.

Core Purpose: Capture both the final recommendation and supporting evidence to prevent purpose drift during implementation.

New here? SKILLS.md is the user-facing overview — a one-line blurb for every /rdr-* skill and how each maps to the stages of this process.

Install

This repo is a Claude Code and Codex plugin. Installation has two parts: get the engine (the /rdr-* skills + stages/, prompts/, TEMPLATE.md), then bind each project that will use it. The engine is shared; the binding is per-project.

1. Get the engine

• Claude marketplace plugin — installs to your user config (~/.claude) or a single project (.claude/); scope only changes where the engine lives.

  /plugin marketplace add cwensel/rdr
  /plugin install rdr@rdr
  

  Remove with /plugin uninstall rdr@rdr.

• Codex marketplace plugin — metadata lives in .agents/plugins/marketplace.json, the manifest in .codex-plugin/plugin.json; Codex installs into a versioned cache.

  codex plugin marketplace add /path/to/rdr
  codex plugin add rdr@rdr
  

  Remove with codex plugin remove rdr@rdr.

After any install or upgrade, re-run /rdr-init to refresh the version-stamped engine path recorded in the marker.

2. Bind a project — /rdr-init

Open the consumer project (a git repo; not $HOME, the engine, or the plugin dir) in your harness, then run the skill:

/rdr:rdr-init            # smart: infers locations, asks only if it can't, discloses them

Run /rdr-init from inside the consumer project, once per project — never globally. It writes a per-project seam (the gitignored .rdr/ data files + a worktree-invariant .rdr-workspace marker), scaffolds the RDR home + its index README, and offers the optional SessionStart seam hook. A preflight enforces this: it hard-stops if cwd isn't a git repo, is the engine repo, or is the installed plugin dir. Installing the plugin alone does not set up a project — init does.

Flags:

/rdr-init	smart default — bind this repo only (repo-local seam); infer locations, ask only on a genuine fork, disclose
/rdr-init --interactive	force the location questions (records, evidence — each can point at its own repo — tracked vs gitignored)
/rdr-init --defaults	take all defaults silently (scripted setup)
/rdr-init --workspace	run from the parent to bind all sibling repos into one shared seam ($WS/.rdr-workspace) they inherit
/rdr-init --reconfigure	change an existing project's locations (migrates existing RDRs or stops for a manual move)

Scope — local by default, workspace by choice. By default /rdr-init binds just the current repo: the seam ($PROJECT/.rdr/), records, and evidence all live inside it. This is the common single-repo case — run it and you're done.

Optionally, run it from the parent with --workspace to bind every folder under that parent into one shared RDR process. It writes a shared marker at the parent ($WS/.rdr-workspace) that all sibling repos inherit, so they author RDRs against the same flow. Because the seam is just a path map, the workspace also lets the records and evidence live in their own repos — separate from the code repo you're working in — rather than being pinned to the current repo. A repo-local seam still wins over a shared one (nearest-wins) without touching it, so any repo can opt out of the shared setup at any time.

3. Verify, then start

/rdr:rdr-doctor          # read-only health check: seam binds, engine resolves, no broken links
/rdr:rdr-seed <idea>     # start the first record

/rdr-doctor is the go-to whenever a skill reports a stopped: seam error or after a plugin upgrade. The per-project marker exports a five-var contract the skills read: RDR_HOME (engine), RDR_RECORDS (the RDR instances), RDR_EVIDENCE (lens/ spike output — defaults beside records, can point at its own dir/repo), and RDR_ENV / RDR_RESOURCES (the path-map + evidence-index data files).

Indexes

RDRs are indexed per project. Each consumer keeps its RDR instances in its own repo (the engine never holds them), and that consumer's README carries the authoritative Status/Priority table, co-located with the RDR files it lists — e.g. a cli/README.md listing a cli/ RDR set.

This README is the cross-project process manual for authoring RDRs: the workflow, finalization gate, pre-lock review rounds, and post-mortem process below apply to every project's RDRs regardless of which index lists them.

Workflow