| name | authoring-rfds |
| description | Write and structure RFDs (Requests for Discussion) for the Symposium project. Use when creating a new RFD, drafting design proposals, or reviewing RFD content for style compliance. |
Authoring RFDs
What is an RFD?
An RFD is a proposal for a non-trivial change. It lives in md/rfds/<name>/README.md and follows the template in md/rfds/TEMPLATE/README.md. RFDs are submitted as PRs; once merged they appear under the "Accepted" section of md/SUMMARY.md. When implementation is complete, they move to "Completed".
Process
- Create a subdirectory under
md/rfds/ (e.g., md/rfds/my-feature/).
- Copy the template from
md/rfds/TEMPLATE/README.md into md/rfds/my-feature/README.md.
- Fill in each section.
- Add the RFD to
md/SUMMARY.md under the "Accepted" heading.
- Open a PR. Discussion happens on the PR.
- Implementation PRs reference the RFD and update its status section.
Style guide
Voice and tone
- No promotional text, overstated claims, or dramatic writing style.
- Be factual, brief, and to the point.
- Write as if explaining to a colleague who is already familiar with the project.
- Avoid filler phrases like "This exciting new feature will revolutionize..." โ just say what it does.
Structure
- Lead with concrete concepts, then generalize. Show the specific thing first, explain the pattern second.
- Include examples. A short code snippet or config fragment is worth more than a paragraph of description.
- Keep sections short. If a section exceeds ~30 lines, consider splitting it or using sub-headings.
Proposed documentation
- Include subchapters with proposed user-facing documentation (e.g., what the relevant reference page or guide section would look like after the change lands).
- This serves two purposes: it forces concrete thinking about how the feature is presented, and it gives reviewers something tangible to react to.
- Place these in additional files within the RFD directory (e.g.,
md/rfds/my-feature/proposed-reference.md).
Frequently asked questions
- Each FAQ should be a subsection with a question, like
### Why is this a good idea?. This makes for easy linking.
Implementation plan
- Break the work into small, independently mergeable steps.
- Each step should leave the codebase in a working state.
- Describe the tests you will use to verify that this step was successful.
- Use subsections for each step, with a heading like
### Step 1: Describe the step
Example: good vs. bad
Bad:
This powerful new predicate system will unlock incredible flexibility for plugin authors, enabling them to express complex activation conditions with ease.
Good:
Add a shell(...) predicate that runs a command and holds when exit code is 0.
predicates = ["shell(which cargo-nextest)"]
