---
id: govctl-org/govctl/rfc-writer
version: "cb606a0a"
license: MIT
install: manual
updated: 2026-07-27
---

# rfc-writer — RFC Writer guides you through composing normative RFCs—product contracts with observable obligations, invariants, and compatibility rules. It enforces separation between specification prose and implementation details, ensures each clause is independently testable, and hands off lifecycle operations to dedicated governance tools. Use it to author the contract itself, not design rationale or execution scope.

Publisher: govctl-org · Stars: 239 · Updated: 2026-07-27

Install (manual): `git clone https://github.com/govctl-org/govctl`

## SKILL.md

# 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:

```bash
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.


[View on SkillFed](https://skillfed.io/govctl-org/govctl/rfc-writer) · [View on GitHub](https://github.com/govctl-org/govctl)