rfc-writer

name	rfc-writer
description	Write well-structured RFCs with normative clauses. Use when: (1) Creating a new RFC, (2) Adding or editing RFC clauses, (3) User mentions RFC, specification, or normative requirements
allowed-tools	Read, Write, Edit, Bash, Glob, Grep, TodoWrite
argument-hint	["optional RFC topic"]

RFC Writer

Write RFCs that are precise, complete, and follow govctl conventions.

Invocation Mode

This helper skill may be used standalone or by /discuss, /gov, /spec, or /migrate. It is responsible for RFC content and clause quality, not RFC lifecycle verbs. Use /spec or /gov for govctl rfc finalize, bump, or advance.

Quick Reference

govctl rfc new "<title>"
govctl clause new <RFC-ID>:C-<NAME> "<title>" -s "<section>" -k <kind>
govctl clause edit <RFC-ID>:C-<NAME> --stdin <<'EOF'
clause text
EOF

RFC Structure

Every RFC should have:

1. Summary clause (informative) — what this RFC covers and why
2. Specification clauses (normative) — the actual requirements
3. Rationale sections within clauses — why each requirement exists

Summary Clause Template

govctl clause new <RFC-ID>:C-SUMMARY "Summary" -s "Summary" -k informative
govctl clause edit <RFC-ID>:C-SUMMARY --stdin <<'EOF'
Brief overview of what this RFC specifies and why.

**Scope:** What is covered and what is not.

**Rationale:** Why this specification is needed.
EOF

Normative Clause Template

govctl clause new <RFC-ID>:C-<NAME> "<Title>" -s "Specification" -k normative
govctl clause edit <RFC-ID>:C-<NAME> --stdin <<'EOF'
The system MUST ...
The system SHOULD ...
The system MAY ...

**Rationale:**
Why this requirement exists.
EOF

Writing Rules

RFC 2119 Keywords

Use these keywords in ALL CAPS in normative clauses:

Keyword	Meaning
MUST	Absolute requirement
MUST NOT	Absolute prohibition
SHOULD	Recommended but not required
SHOULD NOT	Discouraged but not prohibited
MAY	Optional

Quality Checklist

• Be specific. Avoid vague terms: "appropriate", "reasonable", "as needed". Say exactly what.
• Include rationale. Every normative clause should explain why, not just what.
• One requirement per sentence. Don't chain MUST/SHOULD in a single sentence.
• Reference existing artifacts. Use [[RFC-NNNN]] or [[ADR-NNNN]] syntax.
• Testable. Each MUST/SHOULD should be verifiable — if you can't test it, rewrite it.

Clause Naming

• Use C- prefix followed by a descriptive uppercase name with hyphens
• Good: C-VALIDATION, C-ERROR-FORMAT, C-WORK-DEF
• Bad: C-1, C-Misc, C-stuff

Section Types

Section	Clause Kind	Content
Summary	informative	Overview, scope, rationale
Specification	normative	MUST/SHOULD/MAY requirements
Rationale	informative	Extended explanation

Rendering Rules

The renderer auto-generates structural elements. Do NOT include these in clause text:

• Clause heading (### [RFC-XXXX:C-NAME] Title) — auto-generated from metadata
• *Since: vX.Y.Z* — auto-generated from the since JSON field
• > **Superseded by:** ... — auto-generated from the superseded_by field
• Amended: ... — does not exist; do not hallucinate this

Clause text should contain only the specification prose, rationale, and [[...]] references.

Common Mistakes

Mistake	Fix
Vague MUST: "MUST handle errors appropriately"	Specific: "MUST return Result<T, E> with descriptive error message"
No rationale	Add **Rationale:** section explaining why
Untestable requirement	Rewrite so it can be verified programmatically
Missing cross-references	Add [[RFC-NNNN]] or [[ADR-NNNN]] links
Including Since: in clause text	Don't — the renderer adds it from the since field automatically
Including clause heading in text	Don't — the renderer generates ### [RFC:C-NAME] Title from metadata

Validation and Handoff

• Run govctl check after substantive RFC edits
• Use rfc-reviewer before lifecycle handoff
• Use /spec for clarification-only or artifact-only RFC maintenance
• Use /gov for implementation-bearing RFC amendments