Docs rfc

Create Request For Comments

Create a new RFC document proposing and discussing a change.

Anti-Hallucination Guidelines

RFCs propose changes to real systems, so ground every claim before writing:

1. Verify current state — explore the codebase to understand what exists today
2. Reference actual code — don't invent APIs or patterns; find real examples
3. Check dependencies — confirm libraries/tools mentioned actually exist in the project
4. Validate assumptions — each claim about current state must be verified

Workflow

Phase 1: Explore and Gather Context

Understand the codebase before writing anything. If the Task tool is available, use the Explore agent:

Use Task tool with Explore agent:
- prompt: "Analyze the codebase to understand [RFC_TOPIC]. Find: 1) Current implementation patterns, 2) Related components and their interactions, 3) Existing similar features, 4) Technical constraints. Return verified findings with file paths."
- subagent_type: "Explore"

No Task tool available — explore directly with grep/glob/read before writing, covering the same four questions (current patterns, related components, existing similar features, technical constraints). Either way, keep what you find: it feeds the Background and Detailed Design sections in Phase 6.

Phase 2: Parse Arguments

1. Extract proposal title from $ARGUMENTS
2. Check for a variant keyword: minimal, standard, or detailed
3. If a variant is found, remove it from the title
4. Default variant: standard

Phase 3: Determine RFC Number

• Scan docs/rfc/ for existing files matching RFC-XXXX-*
• Increment the highest number by 1 (start at 0001 if none exist)
• Format as a 4-digit padded number (e.g. 0001, 0023)

Phase 4: Sanitize Title for Filename

Convert the title to kebab-case, lowercase, special characters stripped. Example: "Add GraphQL API Support" -> add-graphql-api-support

Phase 5: Get Author Information

Run git config user.name, falling back to "Development Team" if empty.

Phase 6: Load and Populate Template

Template location: assets/templates/ — select based on variant:

• minimal -> minimal.md — Summary, Motivation, Proposal, Open Questions. Use for small changes.
• standard -> standard.md (default) — adds Rationale and Alternatives, Implementation Plan, Testing Plan, Migration Strategy, Timeline. Use for most feature proposals.
• detailed -> detailed.md — full set including Goals/Non-Goals, Security Considerations, Performance Implications, Monitoring and Metrics. Use for major/architectural changes.

Draft real content for every {{PLACEHOLDER}} present in the selected template — each variant has its own set (metadata fields, body sections, risk tables, alternatives, review history, and so on). Base each one on the Phase 1 findings or on explicit reasoning about the proposal; never leave a placeholder token literally in the output. The written RFC must contain zero unresolved {{...}} tokens.

Phase 7: Create RFC File

• Filename: docs/rfc/RFC-XXXX-kebab-case-title.md
• Ensure docs/rfc/ exists, write populated content, set status to "Draft"

Phase 8: Report Creation

Show the RFC number, title, file path, and next-step guidance (share for feedback, update status as it progresses).

Usage Examples

docs-rfc "Add GraphQL API Support"
docs-rfc minimal "Update Logging Format"
docs-rfc detailed "Migration to Microservices Architecture"

RFC Status Lifecycle

Draft -> In Review -> Accepted / Rejected (or Withdrawn at any point, Implemented after accepted work ships). Update the status field as the RFC moves through review.

Good Practices

• Write the RFC before starting implementation, not after
• Include concrete examples and real code references, not hypotheticals
• Document alternatives considered and why they were rejected
• Link related ADRs, issues, or other RFCs
• Keep it updated as a living document during review