new-rfc

name	new-rfc
description	Use this skill when the user wants to propose, draft, or open an RFC (request for comments). Triggers on "RFC", "propose a change to…", "let's get input on…", "draft a proposal". Do NOT use for already-decided things (use `new-adr`) or for changes that fit in a normal PR.

Skill: new-rfc

Open a new RFC in docs/rfc/ to propose a change that warrants discussion before implementation.

When to invoke

Confirm one of:

• The change touches multiple crates or affects the public library API.
• The change reverses or contradicts a previous ADR.
• The change adds, removes, or modifies a top-level convention in CONTRIBUTING.md or docs/CHARTER.md.
• The user explicitly wants discussion before implementation.

If the change fits inside a single crate and breaks no public interface, push back: a normal PR is enough.

Procedure

1. Create docs/rfc/ if it doesn't exist yet:

   mkdir -p docs/rfc
   

2. Find the next number:

   ls docs/rfc/ 2>/dev/null | grep -E '^[0-9]{4}' | sed 's/-.*//' | sort -n | tail -1
   

   Add 1, zero-pad to 4 digits. If no RFCs exist yet, start at 0001.

3. Pick a kebab-case title. Keep it short and descriptive.

4. Create the file with this structure:

   # RFC-NNNN: <Title>
   
   **Status:** Draft
   **Date:** YYYY-MM-DD
   **Author:** <name>
   
   ## Summary
   
   <One paragraph. What are we proposing and why?>
   
   ## Motivation
   
   <What problem does this solve? What's the evidence it's a real problem?>
   
   ## Proposal
   
   <The concrete change. Be specific enough that someone could implement
   it without asking you questions.>
   
   ## Drawbacks
   
   <What are we giving up? What could go wrong? If you say "none", push
   back — there are always drawbacks.>
   
   ## Alternatives considered
   
   - **Do nothing** — <why that's worse than this proposal>
   - **<Alternative>** — <why rejected>
   
   ## Follow-on artifacts
   
   <After acceptance, list the ADRs, spec changes, or CONTRIBUTING.md
   edits that will implement this RFC.>
   

5. Help the user draft the sections. The two most often under-developed are:

   • Alternatives considered — "do nothing" must be included. If the user can't articulate any alternatives, the proposal isn't yet honest.
   • Drawbacks — if they say "none", push back.

6. Set status to Draft until the user is ready to circulate, then Open.

7. Create or update docs/rfc/README.md to add the RFC to a table:

   | RFC | Title | Status |
   | --- | ----- | ------ |
   | [RFC-0001](0001-<title>.md) | <title> | Draft |
   

After acceptance

When the RFC is accepted, the Follow-on artifacts section should list concrete next steps — usually one or more ADRs, edits to CONTRIBUTING.md, or a new phase added to docs/PLAN.md. The RFC itself then stays as historical record.