Background
To talk about MRDRs, we first need to take about MADRs, which are awesome:
Building and evolving a group of MADR documents alongside your project is a great way to capture key architectural decisions, including the "why" and the alternatives, so you never need to look back later and wonder what the heck is going on with the project's design. They're also a great reference for agentic context, where they can help "pin" specific decisions that code generation and other session activities are then shaped by.
But a MADR only captures the architectural decision: a specific point of the design. There's another, more ephemeral artifact that comes up again and again. It's incredibly useful, yet I haven't seen an analogous standard emerge, and several implicitly competing conventions are in use across different agents, harnesses, and toolchains. So, at the risk of adding to the classic XKCD fallacy, I'm going to propose one here.
I'm specifically referring to "plans" or "roadmaps." These are a cornerstone of both agentic development (many harnesses have their own implicit or version-controlled structures) and human architecting, closing the gap between "design" and "development" so we can take an idea and actually start coding. I'm calling this artifact an MRDR, for "Markdown Roadmap Decomposition Record." (It's not entirely a backronym, but you can probably guess that a secondary motive for the name is the potential for some puns "so great they're to die for".)
In short: a MRDR is a version-controlled, per-feature roadmap, broken into phases with testable completion criteria and ordered subtasks.
Purpose
What goes into a roadmap or plan? If we wanted to define (or let emerge, from repeated patterns) an analogue to MADR, what would it need to do? The top-level purpose is to provide a standard plan artifact scheme, but I think there are six specific requirements an MRDR standard needs to satisfy (the "shall" here is meant in the RFC 2119 sense):
A MRDR shall be accessible by humans and agents in plaintext.
A MRDR shall be subject to iteration and review (version-controlled).
A MRDR shall be compressed once its work is complete, freeing context while remaining accessible for later "how did we get here" questions.
A MRDR shall decompose work into organized abstractions.
A MRDR shall provide a specific sequence of specific changes to be made.
A MRDR shall be consumable across agents and harnesses without modification.
These are modest, but they matter. Fortunately, what I've seen across my tooling experiences over the past year suggests a "minimal spanning set" of existing approaches that isn't hard to define or utilize.
Scheme
This is the scheme I've seen emerge and found useful in agentic engineering projects. Your mileage may vary, of course.
Each file is one high-level feature with a unique MRDR identifier based on conventional commit tags (i.e.,
FEAT-LOGGER)-
A MRDR file starts with a short, high-level "intent" (often the title of the work item, task, or issue that initially captured what the effort is meant to address). Other helpful top-level content might include:
- References (links) to relevant MADRs (which I typically assume to exist within the same repository, but they're simply Markdown links, so that's not strictly necessary)
- An explicit list of what the MRDR does not capture or try to address
A MRDR file has subsections that break out unique numbered phases
Each phase has an objective and/or a testable "Definition of Done" (DOD)
-
The rest of the phase's subsection consists of ordered checkboxes: subtasks with unique
R.P.Nidentifiers, each describing a specific modification to make (referencing specific files where possible)-
Ris the unique MRDR identifier -
Pis the phase number within the document -
Nis the subtask number within that phase
-
Subtasks are strongly ordered, phases are weakly ordered. That is, subtasks should be addressed in sequence, but phases may be addressed more concurrently, where possible.
Work items, branches, and merge requests are typically scoped to a specific MRDR, whereas specific commits and agent/harness sessions are more likely to be scoped to individual phases
Examples
Here's the first part of a MRDR I have for a roadmap on an ongoing project.
# Roadmap: Shell (Ebiten IDE chrome)
Map-first desktop shell: window, panels, camera, and visual units. No live Sprites required.
Related:
* [ADR-0004](../madr/0004-ebiten-map-shell.md)
* [ADR-0005](../madr/0005-build-artifacts-to-dist.md)
## Phase 1: Runnable window and build hygiene
**Definition of done:** `go build -o dist/piccolo .` produces `dist/piccolo`; `./dist/piccolo` opens a resizable window with top bar, sidebar, map viewport, and status bar; process exits cleanly on Esc.
- [x] **FEAT-SHELL.1.1**: Go module and Ebiten dependency pinned
- [x] **FEAT-SHELL.1.2**: Basic layout chrome (top / side / map / status)
- [x] **FEAT-SHELL.1.3**: `dist/` output via `go build -o`; `dist/` gitignored
- [ ] **FEAT-SHELL.1.4**: Document controls only in diataxis how-to (or keep brief in root README quickstart)
## Phase 2: Camera and map viewport
**Definition of done:** (illustrative) the map viewport pans and zooms with mouse and keyboard, and the status bar shows the current camera position.
- [ ] **FEAT-SHELL.2.1**: (illustrative) Camera type with position and zoom
- [ ] **FEAT-SHELL.2.2**: (illustrative) Pan and zoom input handling
This presents a clean context and enumeration of the actions needed to accomplish each phase, which makes for a very clean handoff to agentic sessions ("Please iterate on Phase 1 from the MRDR in docs/roadmaps/FEAT-SHELL.md..."). It also makes planning and design transparent. Once you have an MRDR written out, it's a very useful file to hand off to other agents for fleshing out, adversarial review, and so on. Active MADRs can be version-controlled and persist between sessions, and future (draft) MADRs can exist concurrently to active development while they are being fleshed out.
After The Fact
One key difference between MADR and MRDR is that a roadmap is, by definition, somewhat ephemeral. Once implementation and verification are finished and the merge request goes in, you no longer need super-detailed records of every change that had to be made, and a growing pile of full-sized MRDRs can pollute your project's context.
Instead, I "compress" completed MRDRs on a regular basis, typically as part of a weekly sprint or release cycle. This means keeping a file like docs/roadmaps/historical.md that aggregates a summary of previously completed MRDRs: the short, high-level intent of each, and maybe a bulleted list of the phases that were developed. For example:
## FEAT-LOGGER
Structured logging with levels and JSON output, including:
- Core API
- Output sinks
- Configuration
The trick is to include just enough information to answer "how did we get here" questions, for both humans and agents, without duplicating what release notes or project tracking systems already record.
anthropic/sonnet-5.5 was used to perform a light editorial pass after the original article was written
Top comments (0)