git:20260205.9d26539 to v1.0.0

---

name: docs-rfc

disable-model-invocation: true

allowed-tools: Read, Write, Grep, Glob, Bash(git *), Task

context: fork

agent: general-purpose

---

# Create Request For Comments

Create a new RFC (Request For Comments) document for proposing and discussing changes.

## Anti-Hallucination Guidelines

**CRITICAL**: RFCs propose changes to REAL systems. Before writing:

1. **Verify current state** - Explore the codebase to understand what exists today

2. **Reference actual code** - Do not invent APIs or patterns; find real examples

3. **Check dependencies** - Verify libraries/tools mentioned actually exist in project

4. **Validate assumptions** - Each claim about current state must be verified

## Workflow

Before writing an RFC, thoroughly explore the codebase to understand current state:

### Phase 2: Parse Arguments

2. Check for variant keyword: `minimal`, `standard`, or `detailed`

3. If variant found, remove it from title

4. Default variant: `standard`

### Phase 3: Determine RFC Number

- Scan `docs/rfc/` directory

- Find highest existing RFC number (format: `RFC-XXXX-*`)

- Increment by 1

- If no RFCs exist, start with `0001`

- Format as 4-digit padded number (e.g., `0001`, `0023`)

### Phase 4: Sanitize Title for Filename

- Convert title to kebab-case

- Remove special characters

- Lowercase all letters

- Example: "Add GraphQL API Support" -> `add-graphql-api-support`

### Phase 5: Gather Context

- Analyze codebase to understand current state

- Identify relevant files and patterns

- Find similar implementations or related features

- Understand technical constraints

### Phase 6: Get Author Information

```bash

# Try to get git author

!`git config user.name 2>/dev/null || echo "Development Team"`

### Phase 7: Load and Populate Template

- Select based on variant:

Replace placeholders:

- `{{RFC_NUMBER}}` - 4-digit number

- `{{RFC_TITLE}}` - Original title (Title Case)

- `{{DATE}}` - Current date (YYYY-MM-DD)

- `{{AUTHOR}}` - Git user name or "Development Team"

- `{{CONTEXT}}` - Gathered context from codebase

- `{{PROJECT_NAME}}` - Git repo or directory name

### Phase 8: Create RFC File

- Filename: `docs/rfc/RFC-XXXX-kebab-case-title.md`

- Ensure `docs/rfc/` directory exists

- Write populated content

- Set initial status to "Draft"

### Phase 9: Report Creation

- Show RFC number and title

- Display file path

- Provide workflow guidance

## Template Variants

### Minimal Template

Quick proposal format for small changes.

**Sections:** Summary, Motivation, Proposal, Open Questions

**Use when:** Small features, minor changes

### Standard Template (Default)

Balanced RFC for most changes.

**Sections:** Summary, Motivation, Proposal, Rationale and Alternatives, Implementation Plan, Testing Plan, Migration Strategy, Open Questions, Timeline

**Use when:** Most feature proposals

### Detailed Template

Comprehensive RFC for major changes.

**Sections:** Summary, Background and Motivation, Goals and Non-Goals, Proposal, Detailed Design, Rationale and Alternatives, Implementation Plan, Testing and Quality Assurance, Migration and Rollout Strategy, Monitoring and Metrics, Security Considerations, Performance Implications, Open Questions and Risks, Timeline and Milestones, Appendices

**Use when:** Major features, architectural changes

## Usage Examples

Basic RFC creation (uses Standard template):

```

With template variant override:

```

## RFC Status Lifecycle

Update status in the RFC as it progresses:

1. **Draft** - Initial proposal, gathering feedback

2. **In Review** - Under discussion, modifications being made

3. **Accepted** - Approved for implementation

4. **Implemented** - Changes have been deployed

5. **Rejected** - Not moving forward with proposal

6. **Withdrawn** - Author withdrew the proposal

## RFC Workflow

### 1. Create RFC

```

### 2. Initial Draft

- Write comprehensive proposal

- Include motivation and context

- Document alternatives considered

- Add implementation plan

### 3. Share for Feedback

- Share RFC with team

- Update status to "In Review"

- Collect feedback in comments or discussions

### 4. Iterate

- Incorporate feedback

- Update proposal as needed

- Address concerns and questions

- Refine implementation details

### 5. Final Decision

- Stakeholders review final version

- Update status to "Accepted" or "Rejected"

- Document decision rationale

### 6. Implementation

- Reference RFC in PRs

- Update RFC with implementation notes

- Mark status as "Implemented" when complete

## Context Gathering Examples

```bash

# For API changes

!`find . -name "*router*" -o -name "*controller*" -o -name "*api*" | head -10`

# For feature additions

!`grep -r "export.*function\|export.*class" --include="*.ts" --include="*.js" . | head -20`

# For infrastructure changes

!`find . -name "*.yml" -o -name "*.yaml" -o -name "Dockerfile" | head -10`

# For performance changes

!`grep -r "cache\|redis\|memcache\|performance" --include="*.py" --include="*.ts" . | head -15`

## Important Notes

- **Write Before Implementing**: Create RFCs before starting work

- **Concrete Examples**: Include real code examples when possible

- **Address Concerns**: Proactively address potential objections

- **Update Actively**: RFC is a living document during review

- **Link Related Work**: Reference ADRs, issues, or other RFCs

- **Clear Language**: Keep accessible to all stakeholders

- **Define Success**: Include measurable success criteria

## When to Create RFCs

Create an RFC when proposing:

- Major feature additions

- Significant refactorings

- Architecture changes

- Breaking API changes

- New technology adoptions

- Process changes

- Performance optimizations with trade-offs

- Security enhancements

- Developer experience improvements

## Best Practices

- **Early Documentation**: Write RFC before implementation

- **Be Specific**: Include concrete examples and details

- **Show Your Work**: Document research and investigation

- **Consider Alternatives**: Show what else was considered and why

- **Realistic Timeline**: Include reasonable milestones

- **Risk Assessment**: Document known risks and mitigation

- **Stakeholder Input**: Identify who should review

- **Clear Outcomes**: Define what success looks like

- **Keep Updated**: Reflect changes made during review