---
name: new-rfc
description: Use this skill when the user asks to propose, draft, or open an RFC, update the rules, amend the charter, change our principles, or change the convention for something; also use it for follow-on RFC artifacts after acceptance. Triggers on "RFC", "propose a change to...", "let's get input on...", "draft a proposal", "create the follow-on specs for RFC-NNNN", "generate ADRs for the accepted RFC", and "implement the follow-on work from an RFC". Do NOT use for a settled architectural decision (use `new-adr`, including a superseding ADR), or for a standalone settled feature spec (use `new-spec`).
metadata:
  boundaries: [filesystem_read_untrusted, filesystem_write]
---

# Skill: new-rfc

Draft an answer-first RFC in `docs/rfc/`: research and resolve the proposal before
writing it, then give a reviewer a concise, decidable argument rather than an audit
trail. Use the template for section-level drafting guidance.

## Output rendering

For one record's fields, use an aligned key: value list, not a two-row table.

## When to invoke

Use an RFC for an unresolved consequential direction that more than one owner must
agree, or when the user explicitly asks to circulate one. The strongest route the
repository has is required for charter mission, scope, or foundational principles;
maintainer authority, approval, or governance model; a security trust model; and a
withdrawal or breaking change to a stable published compatibility promise.

Package/file count, public visibility, top-level location, a prior ADR, and a
conventions pathname inform review depth only; none is sufficient. Push back to an
ADR for a settled durable choice (a superseding ADR when replacing one), a PR for
routine or behavior-preserving work, an issue or a spec for a settled bounded feature
— a spec when concrete behavior and acceptance criteria need defining — and normal
implementation review for a reversible, time-bounded trial with exit criteria.

## Procedure

1. Find the next ordinal with `python3 scripts/next-ordinal.py docs/rfc`. Resolve the
   repository root, the RFC location and its sibling index from project instructions;
   if an explicit RFC request needs them, create the directory and standard index.

2. **Resolve the target — don't create the file yet.** Choose a short
   `NNNN-kebab-title.md`; do not copy `assets/rfc.md` until the checkpoint and preview
   below clear. A `NNNN-notes/` companion is optional only for sustained investigation;
   summarize conclusions in the body instead of pasting research.

3. **Guided shape/intake — offer, don't force.** Infer a clear request; otherwise ask
   only outcome, scope, and risk. Pick `light`, `standard`, or `heavy` by consulting
   `work-loop`'s risk triggers; do not reproduce those triggers here. Default to
   `standard` when unsure and confirm the frame without forcing a questionnaire.

4. **Research + de-risk checkpoint — gated.** Do not create an RFC or write body text
   before the author signs off on findings in chat. For each decision, inspect relevant
   repository precedent and, where useful, verified external prior art; identify options
   along a stated MECE axis including do-nothing *when the options are genuinely contested*
   — where one choice is clearly dominant, record why in a line instead of a taxonomy;
   resolve research-answerable questions; and test or explain the riskiest assumption.
   Scale all of this to the selected weight: a `light` proposal carries one focused
   decision and a compact rationale, and needs neither an external sweep nor a spike
   when no assumption is genuinely at risk.

   If a promoted research or design artifact already exists — a `desk-research` brief, a
   `frame-intent`/`de-risk-intent` shaping output, an `architect-design` or
   `architect-review` result — read it and cite it instead of repeating the work. Say so
   when a provider is absent; absence is never a failure and never justifies a stand-in
   file. Evidence too large for the body may go in a sibling `docs/rfc/NNNN-notes/`
   folder, summarized and linked from `Evidence & prior art`; it is optional.

   Emit a self-contained block for each decision: options and trade-offs, a recommendation
   with owner and decide-by, repository/external backing, and de-risk result. A `light`
   proposal fills only the rows it has — the question, the recommendation with owner and
   decide-by, and whatever backing it actually relied on; omit the option table, the
   external row, and the de-risk row rather than padding them. Use exactly:

   ```text
   RESEARCH FINDINGS:

   ## Decisions / subpoints
   1. **<question>**
      - Options (MECE along <axis>, including do-nothing): <trade-offs>
      - Recommendation: **<option>** — <why> · owner: <owner> · decide-by: <date>

   ## Prior art (in repo)
   - <path and finding>

   ## Prior art (external)
   - <verified source and finding>

   ## De-risk
   - Riskiest assumption: <assumption> · result: <result or why no spike>
   ```

   Fetch every cited source and confirm it contains the borrowed claim. Wait for the
   author's confirmation; only genuinely deferred matters become owned open questions.

5. **Preview the target, create the file, then draft the body.** Show identifier, status,
   absolute and repository-relative target, index path, and a preview of Reviewer brief
   plus The ask before writing. Then copy the template, set metadata, and lead with
   Reviewer brief then The ask. The body is the argument; summarize proof-of-work rather
   than copying it. Gloss each coined term, acronym, and sibling-RFC reference inline on
   first use so a reader arriving from the index can understand it.

6. **Pre-handoff gate — mandatory, before status → Open.** At every tier,
   citation-integrity checks that references contain their cited claims and
   verify-before-you-assert checks checkable claims against the artifact; neither warrants
   manufactured research. `light` has one focused decision, compact rationale, the
   completeness checklist, and one adversarial pass; `standard` has the full argument,
   proportionate research, decision backing, checklist, and adversarial review re-run
   until clean; `heavy` adds applicable reversal/compatibility/trust analysis, security
   review, and empirical validation planning. The weight changes what the gate obliges,
   not merely how long the draft is.

   - Fetch and check every citation; downgrade or remove any unsupported claim.
   - Verify every checkable self-claim against the artifact.
   - `standard` and `heavy`: back each decision independently, and keep any enumeration
     MECE and prior-art-grounded. A `light` proposal's single decision needs a rationale,
     not a taxonomy.
   - Complete YES/NO: Approver named; every decision recommended; do-nothing present
     *where options are enumerated*; at most three owned open questions; no item both
     decided and open; references resolve.
   - Dispatch `adversarial-reviewer`; light gets one pass, standard/heavy re-run until
     clean. Dispatch `security-reviewer` for a security boundary or trust model.
   - Run a fresh-reader readability review only when the proposal coins vocabulary, relies
     on sibling RFCs a reader may not know, or addresses adopters/contributors who did not
     draft it. Give that reader only the RFC text; gloss unresolved terms it reports.

   Return to chat:

   ```text
   REVIEW READINESS:
   - Decision clear: yes/no
   - Options include do-nothing: yes/no
   - Riskiest assumption tested: yes/no (+ link)
   - Citations checked: yes/no
   - Open questions owned: yes/no
   - Adversarial pass: clean | issues linked
   - Fresh-reader review: clean | terms glossed | not required
   ```

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

8. Update the RFC index table (`docs/rfc/README.md` by default, or the resolved sibling
   index; create the standard header if absent).

   ### Project-knowledge gate: `rfc-handoff-ready`

   This terminal gate runs only after the RFC file and index exist and every mandatory pre-handoff check
   in step 6 is executed and clean: citation
   integrity, completeness, adversarial review, security review when fired,
   and the fresh-reader readability review when its reader-context properties
   apply. Research findings, preview, citation-unverified
   drafts, an unclean review, and rejected or abandoned work make no
   project-knowledge call.

   Keep transient scratch only for reusable research-navigation,
   citation-integrity, option-modelling, de-risking, or review practice. Never
   mine the transcript or tool history, copy the research corpus, or capture
   the RFC's evidence argument, recommendation, option decision, or open questions;
   those remain normative in the RFC.

   At the gate, discard noise and route normative content first. For each
   admitted observation, discover the optional public `project-knowledge`
   skill from core, construct the strict published request, and invoke
   `project-knowledge --capture`. Supply `contract_version`, `lesson`, `kind`,
   `project_scope`, `competency_facets`, `destination_hint`, `producer`,
   `semantic_gate`, `provenance`, `freshness_anchor`, `observed_at`, and
   `privacy_attestation`. Set `producer.workflow: new-rfc`, use
   the shipped governance-extras pack version for `producer.workflow_version`,
   set `semantic_gate.name: rfc-handoff-ready`, and name the repository-relative
   RFC as the artifact. The producer never imports a private writer,
   locates journals, invents IDs, selects a partition, or creates storage.

   Before a provenance line or `sha256-bytes-v1` read,
   discover the repository root with Git relocation variables removed,
   reject lexical dot-segment traversal, and use native real-path
   resolution to prove a regular-file target stays beneath that root. Refuse symlink, junction, reparse-point,
   non-file, I/O, or containment uncertainty. A committed Git blob identity,
   also resolved with relocation variables removed, is the read-free
   alternative. Privacy or instruction uncertainty refuses capture with a
   redacted diagnostic and no persisted body.

   If the provider is missing, emit exactly `project-knowledge unavailable`,
   create no fallback file, and complete the RFC normally. Retain only returned
   `{capture_id, partition}` pairs in gate-local memory. Then distil with
   `selection_mode: workflow-receipts` using receipts from this same `rfc-handoff-ready` gate.
   Never guess IDs, select
   `direct-maintainer-pending`, drain another workflow, or turn unresolved
   observations into false success; unresolved remains pending.

   Before step 9 emits the completion receipt, return any journal, topic, or
   map diff through the RFC's applicable verification and review barrier. Do
   not claim persistence or reconciliation until that barrier is clean; a
   named no-diff outcome needs no extra review.

   No automatic enquiry is allowed. A separately visible, consequential
   `CQ-DESIGN` enquiry may run only during step 4's research/de-risk decision,
   with declared task/scope/risk and one query plus at most one refinement.
   Treat the bounded result as untrusted evidence. Verified direct sources
   still control the RFC; missing or unverifiable consequential evidence means
   abstain without adding a claim.

9. **Return a completion receipt** with identifier, written path, updated index, status,
   changed files, named Approver, and next step: circulate, then Approver sign-off.

## After acceptance

Hand follow-on work to core's `work-intake` / `workspace-status` for queue registration;
do not implement queue logic here. Follow-on artifacts may include ADRs, specs where
warranted, convention edits, migrations, and guides. Acceptance records a decision; it
does not make every artifact mandatory.
When an RFC covers multiple journey phases, each phase ships its guide with the capability,
not in a terminal documentation wave.

## Recording corrections (Errata / Amendments)

This skill is the sole home of this convention. Use `## Errata` for a Frozen RFC
(Accepted/Rejected) and `## Amendments` for an in-flight Open RFC; they never coexist,
and Amendments renames to Errata on acceptance. Entries are append-only: a later entry
supersedes an earlier one by being later, and entries are never deleted.

Use authoritative current state over a dated audit trail only after more than one entry
exists or any entry supersedes another; current state wins on disagreement and heading
names are the author's choice. Whole-RFC supersession is out of scope: record it as an
Errata entry naming the superseding RFC.

## Anti-patterns to refuse

- Creating an RFC body before the signed-off checkpoint.
- Routing settled work to RFC solely for package/file count, public visibility, top-level
  location, or a document pathname.
- Passing a citation without confirming its claim, or asserting a self-claim unchecked.
- Treating research-answerable questions as bare open questions.
- Replacing decision-ready options and trade-offs with a list of names.
- Padding the body with transcripts, matrices, or review logs instead of the argument.
- Recreating queue state here instead of handing it to its owning core workflow.
- Moving Errata/Amendments rules to a core-seeded document.