Jean-Pierre

Appearance

View Markdown
References001003100
Referenced by100

RFD 041: RFD Lifecycle Enhancements ​

Summary ​

This RFD introduces three improvements to the RFD lifecycle: RFD numbers are assigned at Discussion (not at Draft creation), a GitHub tracking issue is created automatically when an RFD is accepted, and two new metadata fields (Extends / Extended by) make directional relationships between RFDs machine-readable.

The tracking-issue half is superseded by RFD 100, which tracks implementation work in tickets instead.

Motivation ​

Three independent problems with the current process motivated these changes.

Numbers are assigned too early. Today, rfd-draft assigns a permanent number on creation. That number becomes a stable reference before the RFD has been reviewed or even finished. This means:

  • Splitting a draft into two focused RFDs requires renumbering, which breaks any in-flight references.
  • Authors pre-assign numbers to related RFDs they intend to write, creating gaps and ordering confusion if any of them are abandoned.
  • The RFD number signals identity and commitment, but it currently signals nothing more than "someone started typing."

Implementation tracking lives in the wrong place. The Implementation Plan section of a design RFD lists phases and steps, but there is no mechanism to track which phases have been completed, link to the PRs that implemented them, or collect the implementation notes that accumulate during development. That information ends up scattered across commit messages, PR descriptions, and nowhere.

RFD relationships are invisible to tooling. When a later RFD extends an earlier design — adding a capability, improving a mechanism, or building on the foundation — that relationship is captured only in prose and TIP callouts. It is not in the metadata header, not in the index, and not queryable. The relationship has to be discovered by reading.

Design ​

1. Deferred Numbering ​

Drafts are created as NNN-title.md — the literal placeholder NNN, not a number. The file header uses NNN in the title and carries no number in the metadata.

When the author runs just rfd-promote NNN-title to advance to Discussion, the tooling:

  1. Assigns the next available sequential number.
  2. Renames the file from NNN-title.md to 041-title.md.
  3. Updates the # RFD NNN: Title heading in the file.
  4. Proceeds with the existing promotion flow (status → Discussion).

From that point the RFD has a stable identity. Other RFDs may reference it by number. Before that point, no number exists to reference.

What this enforces: An RFD in Draft status cannot be linked to by number from another RFD, because it does not have one. This eliminates speculative cross-draft dependencies and forces design relationships to be resolved before both RFDs reach Discussion.

2. Tracking Issues ​

TIP

This section is superseded by RFD 100. Implementation work is tracked in tickets: rfd-promote offers to turn each phase of the Implementation Plan into a ticket carrying Implements: NNN, and one ticket serves as both the tracking item and the prioritised work item. No GitHub tracking issue is created, and the Tracking Issue metadata field is retired.

The original text below is preserved for historical context. Note that it describes issue creation at Discussion; as implemented, it happened at Accepted.

When just rfd-promote advances an RFD to Accepted, a GitHub tracking issue is created automatically alongside the status change.

The issue:

  • Links to the RFD document.
  • Contains a task list generated from the RFD's Implementation Plan by the rfd_open_tracking_issue tool (an LLM-assisted tool in the rfd skill that reasons about the RFD and produces a structured task list; the task list is not a static template).
  • Serves as the canonical place for implementation notes, PR links, and progress tracking.

A Tracking Issue: #XXX line is added to the metadata header:

markdown
- **Status**: Discussion
- **Category**: Design
- **Authors**: ...
- **Date**: ...
- **Tracking Issue**: #XXX

Scope by category:

CategoryTracking issue
DesignAlways
DecisionAlways
GuideOnly if the guide describes a process
with implementation steps
ProcessOnly if the process change has
implementation steps

Lifecycle: When an RFD is abandoned, the tracking issue is closed with a comment stating why. When an RFD is superseded, the tracking issue is closed and linked to the successor's tracking issue.

3. Extends and Extended by Metadata ​

Two new optional metadata fields capture directional extension relationships between RFDs:

markdown
- **Extends**: RFD 028
- **Extended by**: RFD 034, RFD 037

Extends is written in the newer RFD. Extended by is written in the older one. Both are updated by just rfd-extend NNN MMM, which writes Extended by: MMM into NNN and Extends: NNN into MMM atomically.

The relationship is n-to-m: an RFD can extend multiple predecessors, and can be extended by multiple successors. Both fields accept comma-separated RFD numbers.

Distinction from Supersedes: A superseding RFD replaces its predecessor — the old design is no longer the current approach. An extending RFD builds on its predecessor — the original remains largely valid and in effect. RFD 034 extends RFD 028 (adds cheaper model routing); it does not supersede it (the inquiry mechanism is still the approach, just improved).

Constraint: These fields reference only RFDs in Accepted status or later. The deferred numbering policy makes this natural: a draft has no number, so it cannot appear in an Extends or Extended by field.

4. Related RFDs (Automated) ​

A Related metadata field is deliberately not introduced. At scale, maintaining bidirectional Related links manually becomes a burden that outweighs the benefit.

Instead, the VitePress site loader is extended to scan each RFD document for links to other RFDs and surface the results automatically — both as a "Referenced by" list on the individual RFD page and as data available to the index. The Date column in the index is removed; the space is used for relationship indicators instead.

Drawbacks ​

  • Habit change. Contributors are used to getting a number immediately. Drafts that circulate informally as "the thing I'm working on" can no longer be referred to by number. This is a feature, not a bug — but it requires adjustment.

  • rfd-promote is now a bigger operation. It previously changed one line in one file. It now renames a file, updates a heading, creates a GitHub issue, and updates metadata. It must be atomic: if the GitHub issue creation fails, the file rename should not persist.

  • Tracking issues add noise to the GitHub issue tracker. Mitigated by using a dedicated label (rfd) and ensuring the issue titles are clear (RFD-041: ...).

Alternatives ​

Assign numbers at Accepted, not Discussion ​

Numbers could be deferred further — only assigned when consensus is reached. Rejected because Discussion is the point where external references become necessary. Reviewers link to the RFD in comments; other authors need to reference it in their own RFDs; tracking issues need a stable title. Discussion is the right commitment point.

A Related: RFD NNN, RFD MMM field, maintained by authors, was considered. Rejected because the maintenance cost grows with every new RFD written. A site-level automation that scans document links is lower cost and covers the same use cases without requiring authors to remember to update metadata in both directions.

Static tracking issue template ​

A fixed template for all tracking issues (boilerplate + link to RFD) was considered. Rejected because the implementation phases differ significantly between RFDs. A Design RFD with five phases needs five checkboxes; a Decision RFD may need none. The LLM-assisted tool reads the Implementation Plan and generates the task list accordingly.

Non-Goals ​

  • Renumbering existing drafts. Existing Draft-status RFDs at the time this ships keep their numbers under the grandfather clause.
  • Automated tracking issue updates. The tracking issue is created once at promotion. Keeping it current (checking off tasks) is the author's and implementer's responsibility.
  • Related as manual metadata. Covered by website automation.
  • Changes to the Discussion or Accepted lifecycle steps beyond what is described above.

Implementation Plan ​

Phase 1: Deferred numbering tooling ​

Update just rfd-draft to create NNN-title.md with NNN as the literal placeholder throughout (filename, heading, metadata). Update just rfd-promote to detect when the current status is Draft (i.e., the file is named NNN-*.md), assign the next available number, rename the file, and update the heading before changing the status.

Update docs/rfd/001-jp-rfd-process.md to document the new policy.

Depends on: nothing. Can be merged independently.

Phase 2: Tracking issue creation ​

Add rfd_open_tracking_issue to the rfd skill in .jp/config/skill/rfd.toml. The tool accepts the RFD number, title, a URL to the document, and an array of task strings derived from the Implementation Plan; it creates a GitHub issue via gh issue create (or curl against the GitHub API) and returns the issue URL.

Extend just rfd-promote to call this tool when advancing to Discussion, then inject the resulting issue number into the Tracking Issue: metadata field. If issue creation fails, the promotion aborts before renaming the file.

Update docs/rfd/001-jp-rfd-process.md to document the tracking issue field and its lifecycle (close on abandon/supersede).

Depends on: Phase 1 (the promotion command is extended, not replaced).

Phase 3: Extends / Extended by metadata and rfd-extend command ​

Add just rfd-extend NNN MMM to the justfile. The command adds Extended by: RFD MMM to NNN's metadata and Extends: RFD NNN to MMM's metadata. Handle comma-separated lists: if the field already exists, append rather than replace.

Update the metadata header documentation in 001-jp-rfd-process.md and the tooling table.

Depends on: nothing. Can be merged independently of Phases 1 and 2.

Extend the VitePress data loader (docs/.vitepress/loaders/rfds.data.js) to parse each RFD document for Markdown links matching the pattern NNN-*.md and record the set of referenced RFD numbers. Expose this as a references field on each RFD data object. Compute referenced_by as the inverse. Update the index page to use this data: remove the Date column, add a references indicator, and surface referenced_by on individual RFD pages.

Depends on: nothing. Can be merged independently.

References ​