rfc-writer

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; and
• rfc-reviewer has no unresolved blocker before lifecycle progression.

Use spec for artifact-only maintenance and gov when the RFC change carries implementation work.