| name | rfc-writer |
| description | Write precise, implementation-independent RFCs with testable normative clauses and correct lifecycle handoff |
| allowed-tools | Read, Write, Edit, Bash, Glob, Grep, TodoWrite |
| argument-hint | [optional RFC topic] |
RFC Writer
Write the product contract: observable obligations, invariants, interfaces, and
compatibility rules. RFCs are normative artifacts, not design diaries, code
sketches, or task plans.
This helper owns RFC content quality. Use spec or gov for lifecycle
operations such as finalization, version bumps, phase changes, deprecation, and
Clause supersession.
Discovery
Inspect the RFC, its relevant Clauses, and governing references before writing:
govctl rfc show <RFC-ID>
govctl clause show <RFC-ID>:<CLAUSE-ID>
govctl search <topic>
Use govctl rfc --help, govctl clause --help, and subcommand help for current
syntax. Clause operations always use the root govctl clause resource.
Hard Stops
- Do not implement, accept, bump, advance, deprecate, supersede, or delete from
this helper. Hand lifecycle work to
spec or gov.
- Do not put a new obligation in an ADR or Work Item to avoid amending the RFC.
- Stop when the requested contract conflicts with normative content or its
lifecycle state is unclear.
- Do not edit lifecycle-owned metadata such as Clause
since.
- Do not reproduce headings or status metadata generated by
govctl render.
Writing Policy
Put Contract In The RFC
A normative statement belongs here when an external observer, validator, stored
artifact, script, or integration can determine whether it is true. It should
remain valid if private types, functions, modules, or implementation languages
change.
Include externally relevant behavior, validation and error semantics, lifecycle
and compatibility rules, and public or persisted representations. Move design
choice and trade-off rationale to an ADR, execution scope to a Work Item, and
transient evidence to loop state or the final response.
Use RFC 2119 keywords in uppercase in normative Clauses. Make each obligation
specific, independently testable, and unambiguous about its subject and
conditions. Prefer one obligation per sentence. Explain why a normative Clause
exists without turning its rationale into a second requirements inventory.
Use informative Clauses for scope, overview, and extended explanation. Use
descriptive C-UPPER-CASE Clause IDs and [[RFC-NNNN:C-NAME]] or
[[ADR-NNNN]] references where another artifact owns relevant authority or
rationale.
Preserve Authoring Boundaries
RFC text may describe an external schema or syntax when that representation is
itself contractual. It should not prescribe private field layouts, language
types, function signatures, helper names, module organization, implementation
steps, or validation logs.
The renderer owns RFC and Clause headings, Clause since, supersession markers,
and other structural metadata. Clause text contains only specification prose,
rationale, and artifact references.
govctl rfc show <RFC-ID> presents the current projection and omits obsolete
body content. Use --history for full supersession history. Rendered Markdown
remains the archival projection.
Respect Lifecycle State
The governing rules are [[RFC-0000:C-STATUS-LIFECYCLE]],
[[RFC-0000:C-PHASE-LIFECYCLE]], [[RFC-0000:C-CLAUSE-DEF]], and
[[RFC-0002:C-LIFECYCLE-VERBS]].
- Draft content remains unpublished until finalization; draft RFCs are not
version-bumped.
- Normative content in
spec refines the current candidate without another
bump.
- Content edits in
impl, test, or stable create an amendment that requires
the authorized version lifecycle before further phase progression.
- Entry to
impl seals the candidate baseline. A version-changing bump opens
the next candidate from impl, test, or stable; it does not retarget an
open spec candidate.
- Deprecated RFCs cannot start another version lifecycle.
Clause version assignment is lifecycle-owned. Draft Clauses receive since at
finalization; Clauses created in normative spec receive the current version;
Clauses created later remain pending until a content bump. An unreferenced
Clause may be deleted while its RFC is draft, or while it belongs only to the
current normative spec candidate (since equals the current version).
Inherited Clauses require deprecation or supersession.
Completion Evidence
Before handoff:
- every normative statement passes the observable, implementation-independent,
and testable contract test;
- content does not duplicate renderer-owned structure or another artifact's
authority;
- references and project tags are current;
govctl check passes after substantive edits; andrfc-reviewer has no unresolved blocker before lifecycle progression.
Use spec for artifact-only maintenance and gov when the RFC change carries
implementation work.
