RFC Writer

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

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:

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

Common Mistakes